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).

Repo Start Page

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).

Create Fork

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

For example:

[rhager@sunfire02 XGC-Devel]$ git remote -v
origin  https://rhager@github.com/rhager/XGC-Devel.git (fetch)
origin  https://rhager@github.com/rhager/XGC-Devel.git (push)
upstream    https://rhager@github.com/PrincetonUniversity/XGC-Devel.git (fetch)
upstream    https://rhager@github.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”.