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
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
‘email@example.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 firstname.lastname@example.org: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
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
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
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.
See https://www.gnu.org/software/repo-criteria-evaluation.html for an evaluation of the major existing repositories.
For example see this explanation provided by GitLab: http://docs.gitlab.com/ce/ssh/README.html.