Sources¶
We call "sources" your source code in the case of a software project, your HDL and configuration files for gateware and your design files for hardware. It is important to always host your projects in a developer platform (see below). These platforms typically include support to host your sources under version control (mostly Git these days) and also issue management, wikis and other useful features.
Please note that for hardware designs it may not make sense to have your sources (which can sometimes be heavy binary files) in your Git repository. Having a project in a developer platform still makes sense, if only to handle issues and use the wiki or a README file to point to the location of the sources. In the case of CERN, for example, Printed Circuit Board (PCB) design files are often hosted in EDMS. On the other hand, there are many examples out there of Git repos directly hosting hardware design files, especially when the files are text-based, such as those used by KiCad. It is important though to have a single source of truth for the designs, and since PCBs whose layout is done in CERN's drawing office live in EDMS, it is recommended to just point to EDMS from your documents/wiki in the developer platform project.
We have already discussed due diligence in our recommendations. The following aspects are relevant when authoring contributions to open-source projects.
Authoring¶
The work-related contributions authored by CERN employees should show a @cern.ch email address as author.
It does not matter whether these contributions were created during or off working hours.
Users are recommended to use their institute's (i.e. professional) email address.
In the case of Git commits, the author is configured with
$ git config --global user.name "Marie Curie"
$ git config --global user.email "marie@sorbonne-universite.fr"
User identity for developer platforms (GitHub, non-CERN GitLab, etc)¶
For developer platforms other than gitlab.cern.ch, consider creating an identity dedicated for your professional activities: what you do here might get long-lasting visibility.
For CERN employees, please use a @cern.ch email address as primary or secondary address of the developer platform account.
Note that you can change this email address should you need to, for instance if you move on:
your developer platform account is not eternally tied to your CERN employment, you can take it with you.
Hosting¶
All open-source projects should make use of a developer platform such as gitlab.cern.ch or github.com for hosting their main repositories. This will also be a natural place to implement continuous integration, issue tracking and define users' roles within the project.
gitlab.cern.ch vs alternatives¶
If you have contributors without CERN accounts (or with lightweight CERN accounts), gitlab.cern.ch is not a good choice. See the CERN Gitlab documentation for details.
When choosing an alternative to gitlab.cern.ch, think about the ecosystem you want to integrate with: where do most of your users have accounts, so they can easily contribute with commits, pull requests, bug reports, and reviews? Common developer platforms include github.com, gitlab.com, codeberg.org, or bitbucket.com.
If unsure, we recommend github.com as the most common platform today.
Creating the organisation¶
In the context of developer platforms, an organisation is a team of accounts, with common source repositories, security settings, etc.
You should always have multiple owners for an organisation; virtually all developer platforms support this.
It's a good habit to also add an owner representing the "role" (such as "FooBar Project Leader"), using e-groups (such as foobar-dev@cern.ch) as email.
Having multiple owners and the dedicated role e-group enable smoother hand-over of projects should one of the project owners not be capable anymore to hand it over themselves (also known as "business continuity").
For security reasons, all owners should have two-factor authentication (2FA) enabled.
Mirroring to gitlab.cern.ch¶
You should mirror at CERN any repositories hosted elsewhere, possibly in a private repository to avoid ambiguity regarding the project's "home". Such mirroring can be implemented with native Gitlab functionality. The "Pull" model is recommended.