Contribute
Contents
Contribute#
This section aims to explain how we develop and organize, in order to help those that want to contribute to SimPhoNy.
Development tools#
The following are some of the technologies and concepts we use regularly. It might be useful to become familiar with them:
Code organization#
There are 3 main categories of repositories:
The SimPhoNy repository contains the core the SimPhoNy Open Simulation Platform, that the wrappers depend on.
Each wrapper is in its own repository on GitHub or GitLab, mimicking the wrapper-development repository.
docs holds the source for this documentation.
There are also 4 types of branches:
master/main
contains all the releases, and should always be stable.dev
holds the code for the newest release that is being developed.issue branch
is where an specific issue is being solved.hotfix branch
is where a critical software bug detected on the stable release (more on this later) is being solved.
There may be master/main
and dev
branches for several major releases.
Development workflow#
Every new feature or bug is defined in an issue and labelled accordingly. If there is something that is missing or needs improving, make an issue in the appropriate repository.
Generally, the issues are fixed by creating a new
issue branch
from thedev
branch, committing to that branch and making a new Pull/Merge Request when done. A maintainer of the project should be tagged for review. They will review and merge the PR if the fix is correct, deleting theissue branch
afterwards. The changes should be clearly explained in the issue/Pull Request.
Warning
If the issue is a critical software bug detected in the stable release, a
hotfix branch
should be created from the master/main
branch
instead.
After committing to such branch, a new Pull/Merge request (targeting
dev
) should be created. If the fix is correct, the project owner
will merge the PR to dev
, additionally merge the
hotfix branch
to master/main
, and then delete the
hotfix branch
.
Once the features for a release have been developed,
dev
will be merged tomaster/main
. Every new commit in themaster/main
branch generally corresponds to a new release, which is labelled with a git tag matching its version number. An exception to this rule may apply, for example when several critical hotfixes are applied in a row, as it would then be better to just publish a single release afterwards. In regard to version numbering, we adhere to the Semantic Versioning rules.
In the next image it can be seen how the branches usually look during this workflow, and the different commits used to synchronize them:
Coding#
Documentation#
All code must be properly documented with meaningful comments.
For readability, we follow the Google docstring format.
If some behaviour is very complex, in-line comments can be used. However, proper naming and clear operations are always preferred.
Code style#
Code should follow PEP8 code style conventions.
All Python code should be validated by the Flake8 tool. The validation is also enforced on the repository by the continuous integration. Click here to see the specific options with which Flake8 is launched.
All Python code should be reformatted with black and isort. The use of said tools is enforced by the continuous integration. Therefore, we strongly recommend that you use the configuration file bundled with the repository to install the pre-commit framework, that automates the task using git pre-commit hooks.
A few other style conventions are also enforced by the continuous integration through pre-commit (such as empty lines at the end of text files). If you decide not to use it, the CI will let you know what to correct.
Testing#
All complex functionality must be tested.
If some implementation can not be checked through unittest, it should be at least manually run in different systems to assure an expected behaviour.
Continuous Integration#
We currently run the CI through GitHub Actions/GitLab CI.
Code style conventions are enforced through the use of Flake8, black, isort, and various pre-commit hooks.
Tests are automatically run for all pull requests.
For the
simphony-osp
code, benchmarks are run after every merge todev
. Benchmark results are available here. The CI will report a failure when a benchmark is 50% slower than in the previous run, in addition to automatically commenting on the commit.
Contribute to SimPhoNy#
If you are not a member of the
SimPhoNy organisation, rather than creating
a branch from dev
, you will have to fork the repository and create the
Pull Request.
Contribute to the development of a wrapper#
For a sample wrapper, visit the wrapper-development repo.
README files should include:
Information regarding the purpose of the wrapper and the backend used.
Installation instructions.
Any other necessary information for users and other developers.
Contribute to the docs#
If you have any suggestion for this documentation, whether it is something that needs more explanation, is inaccurate or simply a note on anything that could be improved, you can open an issue here, and we will look into it!