Contributing Guide

If you notice a bug or an issue, the best thing to do is to open an issue on the GitHub repository.

If you want to contribute to the code, please follow the steps below:

Coding conventions

The code has been developed following the PeP8 standard and the python Zen. If you have any doubts, try

import this

Documentation

Every function or class should be documented using docstrings which follow numpydoc structure. This web page is written using the reStructuredText format, which is parsed by sphinx. If you want to contribute to this documentation, please refer to sphinx documentation first. You can improve this pages by digging into the docs directory in the source.

To help the contributor in writing the documentation, we have created two nox sessions:

$ nox -s docs
$ nox -s docs-live

The first will build the documentation and the second will build the documentation and open a live server to see the changes in real time. The live server can be accessed at http://127.0.0.1:8000/

Note

To run a nox session, you need to install it first. You can do it by running:

$ pip install nox

Testing

Unit-testing is very important for a code as big as ExoSim 2. At the moment ExoSim is tested using unittest. If you add functionalities, please add also a dedicated test into the tests directory. All the tests can be run with

python -m unittest discover -s tests

Versioning conventions

The versioning convention used is the one described in Semantic Versioning (semver) and is compliant to PEP440 standard. In the [Major].[minor].[patch] scheme, for each modification to the previous release we increase one of the numbers.

Major is to increased only if the code in not compatible anymore with the previous version. This is considered a Major change.
minor is to increase for minor changes. These are for the addition of new features that may change the results from previous versions. This are still hard edits, but not enough to justify the increase of an Major.
patch are the patches. This number should increase for any big fixed, or minor addition or change to the code. It won’t affect the user experience in any way.

Additional information can be added to the version number using the following scheme: [Major].[minor].[patch]-[Tag].[update]

Major is to increased only if the code in not compatible anymore with the previous version. This is considered a Major change.
minor is to increase for minor changes. These are for the addition of new features that may change the results from previous versions. This are still hard edits, but not enough to justify the increase of an Major.
patch are the patches. This number should increase for any big fixed, or minor addition or change to the code. It won’t affect the user experience in any way.
Tag is a string that can be added to the version number. It can be used to indicate the type of release, or the type of change. For example, alpha, beta, release or dev can be used to indicate that the version is not stable yet.
updated is a number to increase for all the changes that are not related to the code patch. This is usefull for development purposes, to keep track of the number of updates since the last release.

The version number is stored in the version keyword of the setup.cfg file.

Source Control

The code is hosted on GitHub and structured as following.

The source has two main branches:

master: this is used for stable and releases. It the public branch and should be handled carefully.
develop: this is the working branch where the new features are tested before been moved on to the `master` branch and converted into releases.

Fork and Pull

If the contributor does not have writing rights to the repository, should use the Fork-and-Pull model. The contributor should fork the main repository and clone it. Then the new features can be implemented. When the code is ready, a pull request can be raised.