Contribution guidelines
=======================

Some general guidelines:

* **Read the contribution guidelines**.<br>
  You have done well so far but keep on reading all the way to the **bottom of this page**.
* Use [expressive function and variable names](https://xkcd.com/910/), e.g.,
  * Good: `get_number_of_structures` (Python)
  * Avoid: `get_nbr_struct` or any variation thereof
  * Good: `get_number_of_allowed_elements` (Python)
  * Avoid: `get_Mi` or any variation thereof
* Document and comment, document and comment, document and comment, document and comment, document and comment ... (it cannot be said too often).
* Always imagine someone else has to be able to read your code. Hence do your
  best at writing [*clean and structured* code](https://www.xkcd.com/1513/).
  * Avoid commenting out blocks of code for "later use/reference" in commits.


Python
------

Code should be [pep8](https://www.Python.org/dev/peps/pep-0008/) compliant and pass [pyflakes](https://pypi.Python.org/pypi/pyflakes).

Any functions/functionality *must* be properly documented.
This includes [docstrings](https://en.wikipedia.org/wiki/Docstring) for functions, classes, and modules that clearly describe the task performed, the interface (where necessary), the output, and if possible an example.
This package uses [NumPy Style Python Docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html).

Good job, you are still reading! [Will you make it to the end?](https://xkcd.com/169/)


Please use spaces
-----------------

While you are entitled to [your own opinion](http://lea.verou.me/2012/01/why-tabs-are-clearly-superior/) this project uses spaces instead of tabs.
Even if you are geeky enough to care and like [Silicon Valley](https://www.youtube.com/watch?v=SsoOG6ZeyUI) you should know that [developers who use spaces make more money](https://stackoverflow.blog/2017/06/15/developers-use-spaces-make-money-use-tabs/).
Also the use of spaces is strongly recommended by our beloved [pep8](https://www.Python.org/dev/peps/pep-0008/) standard.


Commits/issues/merge requests
-----------------------------

### Commit messages

When writing commit messages, generating issues, or submitting merge requests, [write meaningful and concise commit messages](https://xkcd.com/1296/).
The first line should not exceed 78 characters. If you require more space, insert an empty line after the "title" and add a longer message below.
In this message, you should again limit yourself to 78 characters *per* line.


### General guidelines

Bug reports, features suggestions, code review etc are handled via gitlab.
The following workflow is strongly [encouraged](https://xkcd.com/1172/):

#### Preparation phase

As an issue reporter:
* Create an issue.
   * When creating an issue for a __feature request__, it is good practice to describe who the issue is to be developed for, what should be achieved, and ensure that implementation of the feature results in user value.
     Good practice is to write a [user story](https://www.mountaingoatsoftware.com/agile/user-stories), e.g.:
         1. _As a user at a neutron source, I would like to be able to compare_
            _my acquired scattering data with spectra computed using `dynasor`, so that_
            _I can explain my temperature dependent observations._
         2. _As a developer, I would like to easily figure out how to best_
            _contribute to the `dynasor` project._
     It is also a good idea to describe how a successful implementation can be demonstrated.
   * When creating a __bug report__, it is important to describe how the bug can be reproduced.
* Invite comments from users, developers, and other stakeholders via the GitLab interface (e.g., use `@username` to address specific team members in issue descriptions, messages, or discussions)
* Review the input and make adjustments according to input.
  If the issue is considered to take more than five days to complete, try to split it into smaller ones, each with their own user story.
* Once the issue is ready for development, the product owner or a person appointed by the product owner should move the issue to the `To Do` column.

#### Development phase

As a developer:
* If the issue is not already assigned to you, assign it to yourself.
  Move the issue to the `Doing` column.
* Create a branch from the issue via the GitLab interface.
  Ensure that other people can see from the issue which branch you are working on.
* Once the work on the issue has been completed *first* clean up your code and review the [items that will be covered during review (see below)](http://commadot.com/wtf-per-minute/).
  Make sure that the described demonstration can be done, that there are unit tests (or regression tests in case of bug fixes), and developer and user documentation.
* Create a merge request to initiate the review phase.

#### Review phase

As a reviewer:
* If the merge request up for review is not already assigned to you, assign it to yourself.
* The development related to the issue must be reviewed for
  * sufficient test coverage.
  * code passes all existing tests
  * functionality
  * performance
  * code quality
  * compliance to style guidelines
  * addition of new unit tests
  * demonstration is fulfilled
* After all comments/questions raised during the review have been addressed, the code can be merged into master by the reviewer.

As a developer:
* The responsibility for making the code compliant with the above points resides with the developer *not* the reviewer.
