GNU Astronomy Utilities


Previous: , Up: Contributing to Gnuastro   [Contents][Index]


11.11.4 Forking tutorial

This is a tutorial on the second suggested method that you can submit your modifications in Gnuastro (see Production workflow), which is commonly known as forking. Let’s assume you want to start contributing to Gnuastro and you would like to use GitLab163 to host your work remotely and share it with other Gnuastro developers once you are ready. You can create an empty repository on your hosting service webpage. If this is your first hosted repository on the webpage, you also have to upload your public SSH key164 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 ‘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 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. You announce it (see Report a bug) so everyone knows you are working on it. However, if it is a very simple, clear/obvious and straightforward bug to fix you can skip this initial announcement. 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. So you can push all the changes to your hosted repository and delete the branches:

$ 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. Also before starting each issue branch from master, be sure to run git pull in master as shown above, to start your branch (work) from the most recent history point and thus simplify the final merging of your work.


Footnotes

(163)

See https://www.gnu.org/software/repo-criteria-evaluation.html for an evaluation of the major existing repositories.

(164)

For example see this explanation provided by GitLab: http://docs.gitlab.com/ce/ssh/README.html.


Previous: , Up: Contributing to Gnuastro   [Contents][Index]