The Aramis organization on GitHub#
When it comes to software development within the Aramis team, everything goes through the Aramis organization.
All projects should be hosted on Github under the Aramis organization.
Take some time to think about whether you should create a public or private repository. If this is unclear at the moment, start with a private repository and later convert to public if needed.
User managment#
It is assumed that all team members get added to the Aramis organization (it is one of the recommendations of the welcome guide).
Adding members (as well as all other administrative tasks) can be done by one of the “owners” of the organisation.
Users managment is done through teams.
All users are added to the aramis team.
A new user contributing to one of the software can be added to the corresponding team:
This team organization can be useful to manage user rights. For example, Clinica uses two repositories: the public code repository and the private data CI repository. The members of the Clinica team have admin rights on the former and both access and admin rights on the latter. By adding a new user to this team, you don’t have to configure these access rights manually.
When a user leaves, she/he should be removed from the teams and converted to an outside collaborator.
It is very important to regularly clean users who have left in order to reduce the attack surface on the team ressources.
Repositories#
Repositories can basically be public, private, or archived.
It is important to regularly archive repositories that are no longer in use (like small outdated POC, repos used for technical tests during recruitement...).
It is also very important to constantly verify that no internal ressources or information are accessible through public repos.
Branch managment#
Projects have a default branch called main (sometimes master on old projects) which contains stable versions of the code as well as tagged releases.
Projects use a development branch called dev which will contain ongoing un-published work that will be released in the next minor or major release.
Projects use feature branches, branching from dev, to implement specific features.
Before developping a feature, an issue should be created in order to describe the problem or the feature and gather inputs from other developpers if needed.
When using a Github project, the issues should be added to the project under the correct work package. Dates and milestones should be provided if possible and someone should be assigned when decided.
When a feature is ready, it has to be merged into dev through a Pull Request.
Projects#
Projects requiring planning have a dedicated Github project associated to them.
Projects can be divided in work packages and issues from different repos of the organization can be added to these work packages.
For each issue, it is possible to display other kind of metadata such as the starting and ending date, the PR that adresses the issue, the person assigned to it and so on... It is therefore important to put values for these when possible.
Runners#
Runners can be at the repository’s level (in which case they are managed by the team working on the repository), or at the organization level. These runners can be used accross repos which can sometimes be desirable and useful.
Exercice#
Let’s start this tutorial and apply some of the concepts we just looked at. We will create a new repository for a small toy project implementing a “calculator library”. Since we are members of the Aramis team, this calculator will not work with numbers but with images. Our tool should be able to perform arithmetic operations between two images.
No worries we’ll come back to that in the next chapter. Let’s focus on the project settings for now!
Since we don’t want to pollute the Aramis organization, you will create this repository under your personal namespace, but we will use the same conventions as the ones used at Aramis.
First, go to your profile and click on create a new repository. You will need to enter basic information such as shown in the images below:
from IPython.display import Image
Image(filename="../images/github_new_repo_1.png")
Image(filename="../images/github_new_repo_2.png")
For real projects you would need to think about these information as they are very important (especially the licence you decide to use). As this is a toy example, we’ll use the MIT licence.
After clicking the green button, you will be led to the main page of your new repository. You can then copy paste the clone link as shown on this image:
Image(filename="../images/github_new_repo_3.png")
Open you terminal and navigate to a folder in which you want to work and run the clone command (you’d need to modify the url to point to your own repository):
$ git clone git@github.com:NicolasGensollen/calculator-lib.git
Cloning into 'calculator-lib'...
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 5 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (5/5), done.
$ cd calculator-lib
$ tree
.
├── LICENSE
└── README.md
1 directory, 2 files