13.12.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 web page (we recommend Codeberg since it is fully free software³¹¹). By empty, we mean that you don’t let the web service fill your new repository with a README.md file (they usually have a check-box for this). Also, since Gnuastro is a public repository, it is much easier if you define your project as a public repository (not a private one).

If this is your first hosted repository on the web page, you also have to upload your public SSH key³¹² for the git push command below to work. Here we will assume you use the name janedoe to refer to yourself everywhere and that you choose gnuastro as the name of your Gnuastro fork. Any online hosting service will give you an address (similar to the ‘git@codeberg.org:...’ 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@codeberg.org:janedoe/gnuastro.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 does not. 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 do not 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 confirm if others are not already working on it. With the commands below, you make a branch, checkout to it, correct the bug and check if it is indeed fixed. But before all of this, 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

With the commands above, you have opened your favorite text editor (if it is not Emacs, feel free to use any other!) and are starting to make changes. Making changes will usually involve checking the compilation and outputs of the parts you have changed. Gnuastro already has some facilities to help you in your checks during/after development.

developer-build

This script does a full build (from the configuration phase to producing the final distribution tarball). During the process, if there is any error or crash, it will abort. This allows you to find problems that you hadn’t predicted while modifying the files. This script is described more completely in Separate build and source directories. Here is an example of running this script from scratch (the junk is just a place-holder for a URL):

$ ./developer-build -p junk

If you just want a fast build to start your developing, the recommended way is to run it in debugging mode like below:

$ ./developer-build -d

Without debugging mode, building Gnuastro can take several minutes due to the highly optimizable code structure of Gnuastro (which significantly improves the run-time of the programs, but is slower in the compilation phase). During development, you rarely need high speed at run-time. This is because once you find the bug, you can decrease the size of the dataset to be very small and not be affected by run-time optimizations. However, during development, you do need a high speed at build-time to see the changes fast and also need debugging flags (for example to run with Valgrind). Debugging flags are lost in the default highly-optimized build.

tests/during-dev.sh

This script is most commonly used during the development of a new feature within the library or programs (it is also mentioned in Building and debugging). It assumes that you have built Gnuastro with the ./developer-build script (usually in debugging mode). In other words, it assumes that all the built products are in the build directory.

It has internal variables to set the name of the program you are testing, the name of its arguments and options, as well as the location that the built program should be run in. It is heavily commented, so we recommend reading those comments and will not go into more detail here.

make pdf

When making changes in the book, you can run this in the build directory to see your changes in the final PDF before committing. Furthermore, if you add or update an example code block of the book, you should copy-paste it into a text editor and check that it runs correctly (typos are very common and can be very annoying for first-time readers). If there are no problems, you can add your modification and commit it.

Once you have implemented your bug fix and made sure that it works, through the checks above, you are ready to stage, commit and push your changes with the commands below. Since Gnuastro is a large project, commit messages have to follow certain standards that you should follow, they are described in Commit guidelines. Please read that section carefully, and view previous commits (with git log) before writing the commit message:

$ 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.