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:

• Version control: Git, GitHub and GitLab

• Unittest

• Continuous integration

• Python virtual environments/conda

• Docker

• Benchmarks

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 the dev 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 the issue 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 to master/main. Every new commit in the master/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 to dev. 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!