How to contribute to the DQR

The DQR uses a fork-and-pull development model. This workflow is described below (adapted from the LALSuite Contribution Guide, written by Duncan Macleod).

All changes to the Data Quality Report code must be proposed via a merge request, which must then be reviewed by both your reviewers and one of the project maintainers. If you with to contribute new code, or changes to existing code, please follow the following development workflow.

Make a fork (copy) of the detchar repository

You only need to do this once

  1. Go to the DQR repository home page.

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

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

You can do this easily from the command line via:

>> git clone https://git.ligo.org/<your-user-name>/data-quality-report.git

Updating your fork

If you already have a fork of the DQR, and are starting work on a new project you can link your clone to the main (upstream) repository and pull in changes that have been merged since the time you created your fork, or last updated:

  1. Link your fork to the main repository.:

    >> cd data-quality-report
>> git remote add upstream https://git.ligo.org/detchar/data-quality-report.git

    Note: If you are using ssh instead of https, the URL should be git:@git.ligo.org:detchar/data-quality-report.git.

  2. Fetch new changes from the upstream repo.:

    >> git fetch upstream

Creating a new feature branch

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

To create a new feature branch::

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

Hack away

  1. 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. A tutorial of the changes you’re likely to make is available: How to add a new Data Quality Product.

  2. Push your changes to the remote copy of your fork on git.ligo.org.:

    >> git push origin my-new-feature

    Note: For the first push of any new feature branch, you will likely have to use 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

Please note: if you need to add documentation for, e.g., a new task, you can do this within ~/doc/source/tasks. Simply create a new file, add and commit it to the repo, and then push your changes 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 DQR repository home page inviting you to create a merge request out of your newly pushed branch. 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 and provide the pertinent details in the description box. This includes

  • the name of your new product.

  • the permissions awarded to the product (pass, fail, and/or human_input_needed).

  • how the product will be managed (within DQR’s DAG or external to it).

    • if it will be run within the DQR’s DAG, please clearly enumerate all dependencies (e.g.: gwpy >= 0.12.0)

    • if it will run outside the DQR’s DAG, please specify where it will be run and how it those processes will be monitored

  • how you’ve tested the new code.

  • how you’ve tested the new product for efficacy.

If it is possible when you open the merge request, assign it to one of your reviewers. Otherwise, please tag @reed.essick (or one of the other maintainers) and they will assign someone to review the change.