Use of forks¶
Code development is not done on XGC-Devel or XGC-Full-f directly but rather on forks of those repos. A fork shall be created by each developer for the projects the developer leads. A fork is owned by the user who created the fork. Upon creation of a fork, users that have access to the parent repo of a fork will have the same privileges on the fork. The fork owner can restrict access to the fork to a smaller team of developers if necessary. However, never revoke the privileges of the “XGC Admins” team. To create a fork, simply click on the “Fork” button at the top right of the start pages of the XGC-Devel or XGC-Full-f repo (see. Figs. 3 and 4).
Repository start page. For creating a fork of the repo, click on the “Fork” button top right, which will open a dialog box with some options (Fig. 4).
When creating a fork, the user has to decide where to fork the repo. Usually, the choice will be the user’s GitHub account.
For adding or removing users from the fork, switch to the “Settings” tab and select “Collaborators & teams” from the sidebar on the left (Fig. 5). There are two options to add users, teams and collaborators. For adding single users, use the “Collaborators” box, for adding teams of users, use the “Teams” box. You can create your own teams here. Aside from simplifying the management of user privileges, the difference between adding collaborators or teams is that members of a team need to be members of the PU organization whereas even GitHub users who are not members of the PU organization can be added as collaborators. Users can then download local working copies of the forks they are working on with git-clone:
git clone https://[username]@github.com/[fork admin]/[repo name].git
After cloning a child repository forked from the parent repository (PrincetonUniversity/XGC-Devel or PrincetonUniversity/XGC-Full-f), it is recommended to add the URL of the parent repository as the additional remote “upstream”. The default remote URL is “origin” and corresponds to the URL of the repo from which a local working copy has been cloned. For XGC-Devel, the git commands are
git remote add upstream https://[your username]@github.com/PrincetonUniversity/XGC-Devel.git
You can check which remotes already exist in your working copy with the command
git remote -v
[rhager@sunfire02 XGC-Devel]$ git remote -v origin https://firstname.lastname@example.org/rhager/XGC-Devel.git (fetch) origin https://email@example.com/rhager/XGC-Devel.git (push) upstream https://firstname.lastname@example.org/PrincetonUniversity/XGC-Devel.git (fetch) upstream https://email@example.com/PrincetonUniversity/XGC-Devel.git (push)
Creating forks of forks is not recommended. The fork owner can forbid forking by unchecking the box “Allow forking” in the “Settings” tab under “Options” (Fig. 6). If the fork owner wants to allow issue tracking, the corresponding box should be checked in “Settings” → “Options”.