[[TOC]]

Contributing to LALSuite

This page outlines the recommended procedure for contributing changes to the LALSuite repository. Please read the IGWN Computing Guide to GitLab before you start.

Reporting issues

If you have ligo.org authentication, please report issues directly through GitLab. Otherwise, you can use the service desk address to send bug reports by e-mail.

In either case, please include as much detail as possible to reproduce the error, including information about your operating system and the version of each (relevant) component of LALSuite. If possible, please include a brief, self-contained code example that demonstrates the problem.

Note that when an issue is marked as Confidential, currently this means that most internal users will also not be able to see it, but only a small number of people with reporter, developer or maintainer status.

Building LALSuite

Please see here for instructions on building LALSuite from source.

Contributing code

All contributions to LALSuite code must be made using the fork and merge request workflow, which must then be reviewed by one of the project maintainers.

If you wish to contribute new code, or changes to existing code, please follow this development workflow:

Configure Git

You should first ensure that Git is correctly configured on your machine. In particular, you should set your name and email address; these will appear on any commits made to the LALSuite repository. To do this, run these commands:

1.    git config --global user.name "..."

   where ... is replaced with your name (i.e. your human name, not your computer user/login name).

2.    git config --global user.email "..."

   where ... is replaced with your email address, preferably a @ligo.org address if you have one.

You only need to do this once for every machine you will use to develop LALSuite.

For a complete guide to configuring Git for the first time, see here.

Make a fork (copy) of LALSuite

You only need to do this once.

1. Go to the LALSuite repository home page.

2. Click on the Fork button, that should lead you here.

3. Select the namespace that you want to create the fork in, this will usually be your personal namespace.

If you can’t see the Fork button, make sure that you are logged in by checking for your account profile photo in the top right-hand corner of the screen.

Clone your fork

Make sure that you have installed and configured Git-LFS:

git lfs install

for the management of large files. This is required to successfully build and install your development fork.

Then, clone your fork with

git clone git@git.ligo.org:<namespace>/lalsuite.git

Installing pre-commit hooks

LALSuite uses pre-commit hooks to check/fix a variety of code quality issues. These are run by the pre-commit tool, which can be installed using conda, pip, etc. Once pre-commit is installed, it must be configured:

cd lalsuite
pre-commit install

You only need to do this once.

The pre-commit hooks are run every time a new commit is made. If any code quality issues are identified, these will usually be fixed automatically, but you will need to include the extra changes in the commit e.g. using git add. Once all code quality issues are resolved, the new commit will be created.

Keeping your fork up to date

Link your clone to the main (upstream) repository so that you can fetch and pull changes, merge them with your clone, and push them to your fork. Do not make changes on your master branch.

1. Link your fork to the main repository:

   cd lalsuite
   git remote add upstream git@git.ligo.org:lscsoft/lalsuite.git

   You only need to do this once.

2. Update your master branch to track changes from upstream:

   git checkout master
   git fetch upstream
   git branch --set-upstream-to upstream/master
   git pull

   You only need to do this once.

3. Fetch new changes from the upstream repository, merge them with your master branch, and push them to your fork on git.ligo.org:

   git checkout master
   git pull
   git push origin master

4. You can see which remotes are configured using

   git remote -v

   If you have followed the instructions thus far, you should see four lines. Lines one and two begin with origin and reference your fork on git.ligo.org with both fetch and push methods. Lines three and four begin with upstream and refer to the main repository on git.ligo.org with both fetch and push methods.

Making changes

All changes should be developed on a feature branch in order to keep them separate from other work, thus simplifying the review and merge once the work is complete. The workflow is:

1. Create a new feature branch configured to track the master branch:

   git checkout master
   git pull
   git checkout -b my-new-feature upstream/master

   This command creates the new branch my-new-feature, sets up tracking the upstream repository, and checks out the new branch. There are other ways to do these steps, but this is a good habit since it will allow you to fetch and merge changes from upstream/master directly onto the branch.

2. Develop the changes you would like to introduce, using git commit to finalise a specific change. Ideally commit small units of change often, rather than creating one large commit at the end, this will simplify review and make modifying any changes easier.

   Commit messages should be clear, identifying which code was changed, and why. Common practice is to use a short summary line (<50 characters), followed by a blank line, then more information in longer lines.

3. Push your changes to the remote copy of your fork on git.ligo.org. The first push of any new feature branch will require the -u/--set-upstream option to push to create a link between your new branch and the origin remote:

   git push --set-upstream origin my-new-feature

   Subsequent pushes can be made with just:

   git push

4. Keep your feature branch up to date with the upstream repository by doing:

   git checkout master
   git pull
   git checkout my-new-feature
   git rebase upstream/master
   git push -f origin my-new-feature

   This works if you created your branch with the checkout command above. If you forgot to add the upstream/master starting point, then you will need to dig deeper into git commands to get changes and merge them into your feature branch.

   If there are conflicts between upstream changes and your changes, you will need to resolve them before pushing everything to your fork.

Open a merge request

When you feel that your work is finished, you should create a merge request to propose that your changes be merged into the main (upstream) repository.

After you have pushed your new feature branch to origin, you should find a new button on the LALSuite repository home page inviting you to create a merge request out of your newly pushed branch. (If the button does not exist, you can initiate a merge request by going to the Merge Requests tab on your fork website on git.ligo.org and clicking New merge request)

You should click the button, and proceed to fill in the title and description boxes on the merge request page:

• Please provide a descriptive title for the merge request.

• In the Detailed Description section of the description box, please provide a detailed description of the changes, why they are being made, etc. Also indicate appropriate tickets and tests that have been run to determine that the changes work as intended and do not introduce other problems.

• In the API Changes section of the description box, please tick one of the following checkboxes:

  • These changes do not modify the API. Examples of such changes are:

    • C code:

      • No changes to a public C header (i.e. any .h header which is installed in include/lal).

    • Python code:

      • No changes to the arguments of a function/class method which is public (i.e. its name is not preceded by an _).

      • No new public functions/class methods.

      • No new classes/modules.

  • These changes are backwards compatible. Examples of such changes are:

    • C code:

      • Adding a new type/struct/function to a public C header.

    • Python code:

      • Adding a new optional argument to an existing public function/class method, which does not change behaviour if the default value is used.

      • Adding a new public function/class method.

      • Adding a new class/module.

  • These changes are backwards incompatible. Examples of such changes are:

    • C code:

      • Modifying an existing type/struct/function in a public C header.

      • Removing or renaming an existing type/struct/function from a public C header.

    • Python code:

      • Adding a new positional (i.e. non-optional) argument to an existing public function/class method.

      • Removing or renaming arguments (even optional ones) of an existing public function/class method.

      • Changing the return values of an existing public function/class method.

      • Removing or renaming an existing public function/class method.

      • Removing or renaming a class/module.

• If you checked the These changes are backwards incompatible checkbox:

  • In the Justification for Backwards Incompatible Changes section of the description box, please provide a justification for why these changes are necessary and why they need to be done in a backwards incompatible way.

• In the Review Status section of the description box, please provide details on any reviews related to these changes and the associated reviewers.

• It is recommended that you check the box to Remove source branch when merge request is accepted; this will result in the branch being automatically removed from your fork when the merge request is accepted.

Once the request has been opened, one of the maintainers will assign someone to review the change. There may be suggestions and/or discussion with the reviewer. These interactions are intended to make the resulting changes better. The reviewer will merge your request.

Once the changes are merged into the upstream repository, you should remove the development branch from your clone using

git branch -d my-new-feature

A feature branch should not be repurposed for further development as this can result in problems merging upstream changes.

Continuous integration

GitLab runs continuous integration (CI) pipelines on LALSuite to ensure that it builds and passes its test suite on a wide variety of platforms. There are 2 main CI pipelines:

1. The push CI pipeline runs whenever you push commit(s) to your LALSuite fork. This pipeline performs some basic checks that LALSuite still builds and passes its tests with your changes:

   • each component LALSuite package can be build and installed in sequence (the so-called package-level build);

   • LALSuite can build all component packages at once (the so-called top-level build);

   • the LALSuite Doxygen documentation can be built;

   • some basic checks for code style/formatting/whitespace errors, build byproduct files missing from .gitignore, etc.

2. The merge CI pipeline runs when you are ready to submit your changes to the upstream LALSuite fork via a merge request. This pipeline runs a much more comprehensive series of checks that LALSuite still builds and passes its tests with a wide variety of platforms (e.g. MacOS, various Linux distributions) and compilers (e.g. clang, icc, gcc). It also checks that LALSuite packages for a number of package management systems (e.g. RPM, Debian, Conda, Python wheels) are built correctly.

3. (A third CI pipeline runs nightly on the main LALSuite repository fork for deployment tasks, e.g. updating the online documentation).

You can request a subset of the jobs which normally run as part of the merge pipeline to also be run as part of the push pipeline. This is useful if you are making changes to LALSuite which could potentially cause problems with different platforms/compilers, or which could affect the packaging, and you want to test the effect of your changes before submitting a merge request.

For individual commits, you can request a subset of merge pipeline jobs to run by adding key text to the commit message, as listed in the table below. If instead you have a branch where you want a subset of merge pipeline jobs to be run on every push, you can name the branch to match one of the regular expressions given in the table below.

Note: The [ci nightly] and [ci tags] pipelines do not execute any deployment actions with external consequences, e.g. deploying documentation, pushing packages to repositories. These actions can only be executed by the third CI pipeline which runs nightly on the main lscsoft/lalsuite fork.

Pretty code formatting

You may optionally specify that certain C or Python sources should be pretty formatted in a consistent style, which will be enforced by the CI pipelines.

• C code is pretty-formatted using Artistic Style, which supports a number of C coding styles and options. It is enabled by creating files with a .pretty.astylerc extension; the contents of these files are read for the C coding style options to pass to Artistic Style. Three types of files are supported:

  • A C source level file, e.g. lallib/path/to/.MyModule.pretty.astylerc, will pretty-format the C source file(s) lallib/path/to/MyModule.[ch];

  • A directory level file, e.g. lallib/path/to/.pretty.astylerc will pretty-format all C source files in lallib/path/to/;

  • A LALSuite library level file, e.g. lallib/.pretty.astylerc, will pretty-format all C source files in lallib/.

• Python code is pretty-formatted using Black. It is enabled by creating files with a .pretty.black extension; since Black does not take any coding style options, the contents of these files are not examined. Three types of files are supported:

  • A Python source level file, e.g. lallib/path/to/.MyModule.pretty.black, will pretty-format the Python source file lallib/path/to/MyModule.py;

  • A directory level file, e.g. lallib/path/to/.pretty.black will pretty-format all Python source files in lallib/path/to/;

  • A LALSuite library level file, e.g. lallib/.pretty.black, will pretty-format all Python source files in lallib/.

The pre-commit hooks will check that your local changes are pretty-formatted correctly.

More information

• More information regarding the usage of GitLab can be found in the main GitLab documentation.

• See also the LALSuite gitlab wiki pages for some additional developer FAQs.