This section aims to explain how we develop and organise, in order to help those that want to contribute to SimPhoNy.
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
Python virtual environments/conda
There are 3 main categories of repos:
OSP-core contains the nucleus of SimPhoNy, the base on which the wrappers build.
Each wrapper will be in its own repository on GitHub or GitLab, mimicking wrapper_development.
docs holds the source for this documentation.
There are also 4 types of branches:
master/maincontains all the releases, and should always be stable.
devholds the code for the newest release that is being developed.
issue branchis where an specific issue is being solved.
hotfix branchis where a critical software bug detected on the stable release (more on this later) is being solved.
All wrappers and OSP-core are part of a common directory structure:
osp/: contains all the SimPhoNy source code.
core/: OSP-core source code.
wrappers/: wrappers source code.
wrapper_xyz/: one folder per wrapper implementation.
tests/: unittests of the code.
examples/: simple examples of how to use a certain feature.
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 project.
Generally, the issues are fixed by creating a new
issue branchfrom the
devbranch, committing to that branch and making a new Pull/Merge Request when done. An owner of the project should be tagged for review. They will review and merge the PR if the fix is correct, deleting the
issue branchafterwards. The changes should be clearly explained in the issue/Pull Request.
If the issue is a critical software bug detected in the stable release, a
hotfix branch should be created from the
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
Once the features for a release have been reached,
devwill be merged to
master/main. Every new commit in the
master/mainbranch 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 to 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 synchronise them:
All code must be properly documented with meaningful comments.
For readability, we now 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.
All Python code should pass Flake8 tests.
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.
We currently run the CI through Github Actions/GitLab CI.
Flake8 and unittests are automatically run for all PR.
For the OSP-core 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.
cuds_objectas the argument name of your methods (not
The official spelling is
OSP-core(as opposed to osp core, OSP-Core or similar).
Contribute to OSP-core¶
If you are not a member of the SimPhoNy organisation, rather than creating a branch
dev, you will have to fork the repository and create the Pull Request.
Contribute to wrapper development¶
For a sample wrapper, visit the wrapper_development repo.
README files should include:
Information regarding the purpose of the wrapper and the backend used.
A compatibility matrix with OSP-core.
Any other necessary information for users and other developers.