Introduction

The repositories in the SKIRT organization use the GitHub fork and pull workflow model. Anyone can fork a repository, push changes to their personal fork, and initiate a pull request. The changes can be pulled into the original repository by a SKIRT Core Team member, possibly after discussion and/or being adjusted in one or more iterations.

You will need to login to the GitHub website. If you do not already have a GitHub account, create one by pressing the "Sign Up" button at the top of the site's home page and following the instructions.

To get started with contributing to one of the SKIRT project repositories:

On the GitHub web site, fork the relevant repository (for a list, see section GitHub repositories).
Clone this personal fork to your computer, possibly replacing your direct clone of the original repository.

To initiate a pull request:

Ensure that your personal fork and local copy are up to date with the upstream repository.
On your local copy, create a new topic branch for your changes.
Make the desired changes, commit them, and push them to your personal fork.
Test your changes, and repeat the previous line as many times as needed.
On the GitHub web site, go to your personal fork or to the upstream repository.
Create a pull request for the topic branch of your fork to be merged into the master branch of the upstream repository.
Wait for feedback from the SKIRT Core Team.

The sections on this page list the git commands for many of the steps in this workflow. For additional information, refer to GitHub help topics, including:

Configuring git

Configure git so that your identity will be attached to your commits (include the quotation marks):

# Link your commits to your name and GitHub account
git config --global user.name "USERNAME"
git config --global user.email "name@domain.com"

In these lines, replace USERNAME by your GitHub user name and name@domain.com by your email address.

Creating a fork

Go to the GitHub page for the SKIRT/SKIRT9 or SKIRT/PTS9 repository and click the "Fork" button to create a personal fork of the repository on GitHub. A fork is a personal copy of a repository. Forking allows you to experiment with changes without affecting the original repository.

Note: The example commands in this section use the SKIRT/SKIRT9 repository. For the SKIRT/PTS9 repository, replace "SKIRT9" by "PTS9" and clone into a directory named "pts" instead of "git".

Once you've created a personal fork on GitHub, clone this forked repository onto your machine:

# Create local directories on your machine
cd
mkdir SKIRT
cd SKIRT
mkdir release run git
cd git

# Clone your fork into the SKIRT/git directory on your local machine
git clone https://github.com/USERNAME/SKIRT9.git .

In the last line, replace "USERNAME" by your GitHub user name and don't forget the dot at the end to indicate the current directory. On your computer, git will now refer to the forked repo as the "origin" remote. Remotes are repositories hosted on GitHub. You can list them as follows:

# Display all remotes
git remote -v

You'll want to make sure to keep your fork up to date by tracking the original "upstream" repository that you forked. To do this, you'll need to add a remote:

# Add 'upstream' repo to list of remotes
git remote add upstream https://github.com/SKIRT/SKIRT9.git

# Verify the new remote named 'upstream'
git remote -v

Keeping your fork up to date

Whenever you want to update your fork with the latest upstream changes, you'll need to first fetch the upstream repo's branches and latest commits to bring them into your repository. This downloads the remote content but does not update the local repository's working state:

# Fetch from upstream remote
git fetch upstream

# List all branches, including those from upstream
git branch -va

Now, checkout your own master branch and merge the upstream repo's master branch:

# Checkout your master branch and merge upstream
git checkout master
git merge upstream/master

If there are no commits on the local master branch, git will simply perform a fast-forward. However, if you made local changes on master (in the vast majority of cases you shouldn't, see next section), you may have to deal with conflicts. When doing so, be careful to respect the changes made upstream.

Now, your local master branch is up-to-date with everything modified upstream. To bring your fork on GitHub up-to-date as well, push your changes:

# Push any updates to your GitHub fork
git push

Doing your work

Creating a branch

Whenever you begin work on a new feature or bugfix, it's important that you create a new branch. A branch represents an independent version of the code inside the repository. This is the proper git workflow to keep your changes organized and separated from the master branch. In this way you can easily submit and manage multiple pull requests for every task you complete, and keep your local master branch up-to-date with the upstream master branch.

To create a new branch and start working on it:

# Checkout the master branch - you want your new branch to come from master
git checkout master

# Create a new branch named newfeature (give your branch its own simple informative name)
git branch newfeature

# Switch to your new branch
git checkout newfeature

# List all branches; the branch you have checked out has an asterisk (*)
git branch -va

Alternatively, you can create and checkout the new branch with a single command:

# Create and checkout a new branch based on master in one go
git checkout -b newfeature master

Push the new branch to the remote "origin", i.e. your personal GitHub fork:

# Push the new branch to your remote fork
git push -u origin newfeature

# List all local and remote branches
git branch -va

Now, make whatever changes you want to your local working copy of the repository.

Committing your changes

Once you are happy with the changes to your local working copy, it is time to commit them to your personal repository:

# Make sure that your development branch is checked out
git checkout newfeature

# Check the status of modified files
git status

# Add a file to the staging area
git add file.txt

# Or add all modified files to the staging area
git add -A

# Check the status of the staging area
git status

# Commit any changes in the staging area to the local branch
git commit -m "message describing the commit"

# Push the local branch to the corresponding GitHub branch
git push

You can repeat this process as many times you want. This allows you to make complex changes in smaller steps.

Merging with other's changes

Prior to submitting your work, you should make it as simple as possible for the SKIRT Core Team to test, accept, and merge your changes. First fetch upstream master and merge with your repo's master branch:

# Fetch upstream master and merge with your repo's master branch
git fetch upstream
git checkout master
git merge upstream/master

If any commits have been made to the upstream master branch, you should rebase your development branch so that merging it will be a simple fast-forward that won't require any conflict resolution work. With the rebase command, you can take all the changes that were committed on one branch (here the master branch) and replay them on a different branch (here the newfeature branch)

# If there were any new commits, rebase your development branch
git checkout newfeature
git rebase master

Now, push your local changes to your personal fork on GitHub:

# Push your changes to your GitHub fork
git checkout newfeature
git push

Submitting a pull request

Once you've committed and pushed all of your changes to GitHub:

Go to the page for your personal fork on GitHub.
Select your development branch.
Click the pull request button.
Complete the title and description.
Submit the pull request.

If you need to make any adjustments to the code in your pull request after submitting it, just commit these changes to your development branch locally and push your development branch to GitHub. Your pull request will automatically track the changes on your development branch.

Now you can wait until a member of the SKIRT Core Team comments on your pull request and/or merges your changes with the main repository.

Removing the development branch

Once your changes have been merged with the main repository, you're free to delete your development branch:

# Delete local branch that git knows to have been merged
git branch -d newfeature

# Delete local branch in any case
git branch -D newfeature

# Delete remote branch
git push origin --delete newfeature

Resetting your fork

Note: The information in this section is intended for emergency use only.

If you get in trouble you can reset your fork to a clean copy of the upstream repo. Remember that this will discard any changes you made to the local version of the repository and any changes that you pushed to your personal fork on GitHub:

git fetch upstream
git checkout master
git reset --hard upstream/master
git push origin master --force

Merging a pull request

Note: The information in this last section is intended for use by the SKIRT Core Team only.

Automatically merging a pull request

If no further changes to the code in the pull request are required and there are no merge conflicts, you can automatically perform the merge by just clicking the button on the pull request page on GitHub.

Manually adjusting a pull request

Otherwise, you will need to work on a local copy of the pull request. First of all, make sure that your local master branch is up to date with the upstream master into which the pull requests wants to be merged. Then, check out a new branch and pull the changes from the pull request:

# Checkout a new branch with the pull request changes
git checkout -b newfeature master
git pull https://github.com/PR-USER/PR-REPO.git pr-branch

Now test the pull-request code and make any required changes. If you did make any changes, create a new commit and push it back to the original pull request branch (assuming the pull request user did not disable this option):

# Create a new commit with your changes
git commit -a -m "description of changes to pull request"

# Push your commit(s) back to the original pull request branch
git push https://github.com/PR-USER/PR-REPO.git newfeature:pr-branch

After the pull request code has stabilized to an acceptable form, you can finally merge it using the automatic procedure on GitHub, as described before.

Updating your fork

To update your GitHub fork after merging a pull request, once more:

# Checkout your master branch and merge upstream
git fetch upstream
git checkout master
git merge upstream/master
git push

Removing the development branch

Now that you're done with the development branch, you're free to delete it.

# Delete local branch that git knows to have been merged
git branch -d newfeature
# Delete local branch in any case
git branch -D newfeature
# Delete remote branch
git push origin --delete newfeature