======================
Contributing to Horace
======================

Contributing documentation
==========================

If you wish to contribute directly to the documentation, please follow the 6 step process below:

1. If you notice a mistake or a place which could be improved, click the ``Click here to edit`` or the ``Click here to
   add new page`` button at the bottom of the page. This will take you to the GitHub edit page (requires `GitHub account
   <https://github.com/login>`__).
2. Correct the mistake or add new content in the GitHub editor (see `reST documentation
   <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__). **N.B.** It is possible to click the
   ``Preview`` tab at the top to see an approximate render of your changes.
3. Select the ``Create a new branch for this commit`` option at the bottom of the page, with comments describing your
   changes as appropriate in the "Add an optional extended description" box above. **N.B.** For new pages, please note
   in the description a suggestion for the appropriate place the new page should be added, e.g. "Add to User Manual".
4. Click the ``Propose changes`` button, which will take you to the "Open Pull Request" page.
5. In the ``labels`` tab on the right-hand panel select ``documentation`` and ``DO_NOT_CI`` labels. This makes it
   possible for the development team to track the changes more easily.
6. Click ``Create pull request``. This will submit the changes to the development team for review.

Following your submission, the corrections will be reviewed by the development team. After the review, if your changes
are accepted, you should receive an email from GitHub upon their merging. It is possible to see the latest (subject to
change) version of the documentation in the `unstable documentation
<https://pace-neutrons.github.io/Horace/unstable/>`__. The full documentation will be updated on the next Horace
release.

Contributing reports
====================

If you find an error in the code or documentation it is possible to report the issue to the development team to be
handled. This can be done through either the `Horace Help <mailto:HoraceHelp@stfc.ac.uk>`__ email address, or more
directly through `opening a GitHub issue <https://github.com/pace-neutrons/Horace/issues>`__ (requires `GitHub account
<https://github.com/login>`__):

1. Click the green button on the top right which reads ``New issue``.
2. Enter the details of your issue in the "Title" and "Comment" sections, please describe the full extent of your issue
   including, if possible, description of the error, along with any (reasonably sized) inputs or scripts used which raised
   the issue.
3. Click ``Submit new issue``, which will be sent to the development team.

Contributing code
=================

If you wish to develop new code for Horace please get in touch with us: `Horace Help <mailto:HoraceHelp@stfc.ac.uk>`__