# Contributions to pygwinc

The pygwinc project welcomes your contributions.  Our policy is that
all contributions should be peer-reviewed.  To facilitate the review,
please do not commit your work to this repository yourself.  Instead,
fork the repository and create a [merge
request](https://git.ligo.org/gwinc/pygwinc/-/merge_requests/new)
against the main pygwinc master branch for you code changes.

When submitting code for merge, please follow good coding practice.
Respect the existing coding style, which in the case of `pygwinc`
should follow the standard python
[PEP8](https://www.python.org/dev/peps/pep-0008/) style as much as
possible.  Make individual commits as logically distinct and atomic as
possible, and provide a complete, descriptive log of the changes
(including a one line summary followed by a blank line).  Think of
your reviewers when you make code, as your code will be more readily
merged if follow good coding practice.

`pygwinc` comes with a test suite that will calculate all canonical
IFO budgets with the current state of the code and compare them
against traces generated with code from a reference git commit.
Contributors should run the tests before submitting any merge
requests:
```shell
$ python3 -m gwinc.test
```
On initial run a cache of the reference traces will be generated.
Subsequent runs will be sped up by use the existing cache.  Use the
'--plot' or '--report' options to produce visual comparisons of the
noise differences.

If you would like to submit your code changes for inclusion upstream,
and your changes modify the noise calculations such that the tests
fail, then the reference hash will need to be updated to point to the
latest good commit.  This can be done with the '--update-ref' option
to the test script:
```shell
$ python3 -m gwinc.test --update-ref
```
If the no specific reference is provided a pointer to the last commit
will be made.  *Note: reference updates need to be made in a separate
commit after the commits that change the noise calculations.*

Once you submit your merge request, an automated pipeline will run the
test script to validate your changes.  If the tests fail but noise
changes are detected, then the merge request will be rejected.  If
your merge request contains changes to the test reference an alert
will be generated in the merge request indicating that approval by
reviewers is required before merge.


## For admins: approving noise curve changes

As discussed above, merge requests that generate noise changes will
cause pipeline failures.  If the MR properly includes a reference
update, then the failure will only be in waiting for proper approval
of the MR.  A report will also be generated to compare all the noise
changes against the target branch (usually 'master').  See the 'View
exposed artifacts' menu item in the pipeline report.  Once you have
reviewed the report and the code, and understand and accept the noise
changes, click the 'Approve' button in the MR.  Once sufficient
approval has been given, re-run the `review:check_approval` job, which
should now pick up that approval has been given, and if everything
goes ok the pipeline will now succeed, allowing the code to be merged.
Click the 'Merge' button to finally merge the code.