GNU Astronomy Utilities

11.11.4 Forking tutorial

This is a tutorial on the second suggested method (commonly known as forking) that you can submit your modifications in Gnuastro (see Production workflow).

To start, please create an empty repository on your hosting service webpage (we recommend GitLab²¹⁴). If this is your first hosted repository on the webpage, you also have to upload your public SSH key²¹⁵ for the git push command below to work. Here we’ll assume you use the name janedoe to refer to yourself everywhere and that you choose gnuastro-janedoe as the name of your Gnuastro fork. Any online hosting service will give you an address (similar to the ‘git@gitlab.com:...’ below) of the empty repository you have created using their webpage, use that address in the third line below.

$ git clone git://git.sv.gnu.org/gnuastro.git
$ cd gnuastro
$ git remote add janedoe git@gitlab.com:janedoe/gnuastro-janedoe.git
$ git push janedoe master

The full Gnuastro history is now pushed onto your hosting service and the janedoe remote is now also following your master branch. If you run git remote show REMOTENAME for the origin and janedoe remotes, you will see their difference: the first has pull access and the second doesn’t. This nicely summarizes the main idea behind this workflow: you push to your remote repository, we pull from it and merge it into master, then you finalize it by pulling from the main repository.

To test (compile) your changes during your work, you will need to bootstrap the version controlled source, see Bootstrapping for a full description. The cloning process above is only necessary for your first time setup, you don’t need to repeat it. However, please repeat the steps below for each independent issue you intend to work on.

Let’s assume you have found a bug in lib/statistics.c’s median calculating function. Before actually doing anything, please announce it (see Report a bug) so everyone knows you are working on it or to find out others aren’t already working on it. With the commands below, you make a branch, checkout to it, correct the bug, check if it is indeed fixed, add it to the staging area, commit it to the new branch and push it to your hosting service. But before all of them, make sure that you are on the master branch and that your master branch is up to date with the main Gnuastro repository with the first two commands.

$ git checkout master
$ git pull
$ git checkout -b bug-median-stats      # Choose a descriptive name
$ emacs lib/statistics.c
$                                       # do your checks here
$ git add lib/statistics.c
$ git commit
$ git push janedoe bug-median-stats

Your new branch is now on your hosted repository. Through the respective tacker on Savannah (see Gnuastro project webpage) you can then let the other developers know that your bug-median-stats branch is ready. They will pull your work, test it themselves and if it is ready to be merged into the main Gnuastro history, they will merge it into the master branch. After that is done, you can simply checkout your local master branch and pull all the changes from the main repository. After the pull you can run ‘git log’ as shown below, to see how bug-median-stats is merged with master. To finalize, you can push all the changes to your hosted repository and delete the branch:

$ git checkout master
$ git pull
$ git log --oneline --graph --decorate --all
$ git push janedoe master
$ git branch -d bug-median-stats                # delete local branch
$ git push janedoe --delete bug-median-stats    # delete remote branch

Just as a reminder, always keep your work on each issue in a separate local and remote branch so work can progress on them independently. After you make your announcement, other people might contribute to the branch before merging it in to master, so this is very important. As a final reminder: before starting each issue branch from master, be sure to run git pull in master as shown above. This will enable you to start your branch (work) from the most recent commit and thus simplify the final merging of your work.

Read in other formats.

GNU Astronomy Utilities 0.7 manual, August 2018.