.. _contributing:

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 <https://docs.gitlab.com/ee/user/project/merge_requests/>`_, 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 <https://git.ligo.org/detchar/data-quality-report/>`_.
2. Click on the *Fork* button, that should lead you `here <https://git.ligo.org/detchar/datq-quality-report/forks/new>`_.

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:** :ref:`add-new-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 <https://git.ligo.org/detchar/data-quality-report/>`_ 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.