Git
This section contains guidelines about Git
Organization management
A1. Every application or application module developed in the lab must have its own repository under the lab Github organization.
A2. All public repositories should always contain a LICENSE file. If you are unsure about the license they should have, ask.
A3. All public and private repositories should contain a description (independently of the README file) that indicates the project (funded project, semester project, paper,...) they are related to, the main maintainer of the repo, and a one-liner explanation of the purpose.
A4. The semester project code produced by master students should be in a repository under the LDS organization. If they want to work on their personal repositories, they can fork.
A5. When needed, it is preferable to add master/bachelor students and non-LDS employees as external collaborators, but in case they need access to several repositories and it is easier to manage them with teams, they can be added as members, but they should not have (read) access to all the organization repositories in any case.
A6. All members of the organization should have 2FA enabled in their GitHub account.
Branches management
B1. Every repository must have a master branch.
B2. Large new features should have their own branches.
B3. Code owners, i.e. individuals or teams that are responsible for code in a repository, should be defined for all branches by using CODEOWNERS files. The owner of a certain portion of code should be the author of the code or someone who inherited it from the author.
B4. When code owners are not going to be able to take care of their code anymore (e.g., because they are leaving the lab), new owners inheriting their code should be identified. The heirs should be provided with all the necessary information to manage the inherited code.
B5. People inside the lab who intend contributing to a repository (e.g., lab software engineers) should create their personal branches inside the repository and work on them.
B6. People outside the lab who intend contributing to a repository (e.g., students) should fork the repository and work on their own copy of the repository.
Commits management
C1. Developers should commit every time they develop a new feature or, in general, whenever they produced something relevant, even through small code changes.
C2. Developers should not put together in the same commit a huge number of changes with no relations between each others.
C3. Developers should use insightful and descriptive commit messages.
C4. Large files (i.e., > 50 kB) should not be committed. Scripts to retrieve them should be committed (and documented) instead, or git lfs should be used.
C5. Files generated from specification files by third-parties tools (e.g., swagger) should not be committed. On the other hand, the version of the tool used to generate such files should be tracked through metadata or auxiliary files (e.g, go.mod).
Pushes management
D1. Before pushing, developers may edit the commit history of their branches to make it more readable and usable by other developers. To this end they may use, e.g, the amend option of the commit command and the rebase command.
D2. After pushing, developers should not edit the commit history of the remote branches, unless they are sure no-one else is working on those branches (e.g., they are working on their personal development branches).
D3. Direct pushes to the master branch or to branches belonging to different owners should be refused. Developers should only push to the branches they own, and then create appropriate pull requests.
Pull requests management
E1. Pull requests should be small (i.e., they should contain no more than 3 commits related to one feature) and directly mergeable into the destination branch. They should stay open for others to comment.
E2. Big changes should be split in several, successively merged pull requests.
E3. Pull requests should be merged quickly, ideally not more than 3 days should pass between the creation of the PR and the merging.
E4. Pull requests which do not pass the automating testing put in place, if any, should not be merged.
E5. In CI/CD projects, packages should be updated every time a pull request is merged into the master branch, along with the related code running on servers.
Have also a look at how pull requests should be used for development management.
References
Last updated