Previous: Production workflow, Up: Contributing to Gnuastro [Contents][Index]
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 web page
(we recommend GitLab224). If this is your first hosted repository on the
web page, you also have to upload your public SSH key225 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 web page, 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.
See https://www.gnu.org/software/repo-criteria-evaluation.html for an evaluation of the major existing repositories. Gnuastro uses GNU Savannah (which also has the highest ranking in the evaluation), but for starters, GitLab may be easier.
For example see this explanation provided by GitLab: http://docs.gitlab.com/ce/ssh/README.html.
Previous: Production workflow, Up: Contributing to Gnuastro [Contents][Index]
GNU Astronomy Utilities 0.14 manual, January 2021.