diff --git a/docs/source/contribute.md b/docs/source/contribute.md index 129b197..af31c46 100644 --- a/docs/source/contribute.md +++ b/docs/source/contribute.md @@ -6,25 +6,31 @@ in order to help those that want to contribute to SimPhoNy. ### 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 - - Python virtual environments/conda - - Docker - - Unittesting - - Benchmarks + - Version control: [Git](https://git-scm.com/), + [GitHub](https://github.com/about) and + [GitLab](https://about.gitlab.com/) + - [Unittest](https://docs.python.org/3/library/unittest.html) - Continuous integration + - Python virtual environments/[conda](https://docs.conda.io) + - [Docker](https://www.docker.com/resources/what-container/) + - Benchmarks ### Code Organisation There are 3 main categories of repos: - - [_OSP-core_](https://github.com/simphony/osp-core) contains the nucleus of SimPhoNy, the base on which the wrappers build. + - [_OSP-core_](https://github.com/simphony/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](https://github.com/simphony/wrapper-development). - - [_docs_](https://github.com/simphony/docs) holds the source for this documentation. + mimicking + [wrapper_development](https://github.com/simphony/wrapper-development). + - [_docs_](https://github.com/simphony/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. + - `hotfix branch` is 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. @@ -38,10 +44,12 @@ All wrappers and OSP-core are part of a common directory structure: - 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 branch` from the `dev` branch, 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 branch` afterwards. - The changes should be clearly explained in the issue/Pull Request. +- 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. 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 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 @@ -54,15 +62,17 @@ All wrappers and OSP-core are part of a common directory structure: `hotfix branch`. ``` - Once the features for a release have been reached, `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 + `master/main`. Every new commit in the `master/main` branch generally + corresponds to a new release, which is labelled with a [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) 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 + 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_](https://semver.org/) 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: +In the next image it can be seen how the branches usually look during this +workflow, and the different commits used to synchronise them:
@@ -73,32 +83,71 @@ In the next image it can be seen how the branches usually look during this workf ## Coding ### Documenting - All code must be properly documented with meaningful comments. -- For readability, we now follow the [Google docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings). +- For readability, we now follow the + [Google docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings). - 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](https://peps.python.org/pep-0008/). +- All Python code should be validated by the + [Flake8](https://github.com/pycqa/flake8) tool. The validation is also + enforced on the repository by the + [continuous integration](contribute.md#continuous-integration). Click + [here](https://github.com/simphony/osp-core/blob/master/.github/workflows/ci.yml#L12) + to see the specific options with which Flake8 is launched. +- All Python code should be reformatted with + [black](https://github.com/psf/black) and + [isort](https://github.com/PyCQA/isort). The use of said tools is + enforced by the + [continuous integration](contribute.md#continuous-integration). Therefore, + we strongly recommend that you use the + [configuration file](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml) + bundled with the repository to + [install](https://pre-commit.com/#installation) the + [pre-commit framework](https://pre-commit.com/), that automates the task + using git pre-commit hooks. +- A few + [other style conventions](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml) + are also enforced by the continuous integration through + [pre-commit](https://pre-commit.com/) (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 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. +- 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. -- 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](https://simphony.github.io/osp-core/dev/bench/index.html). - 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. +- Code style conventions are enforced through the use of Flake8, black, isort, + and various + [pre-commit](https://pre-commit.com/) + [hooks](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml). +- Tests are automatically run for all pull requests. +- For the OSP-core code, benchmarks are run after every merge to `dev`. + Benchmark results are available + [here](https://simphony.github.io/osp-core/dev/bench/index.html). 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. ### Naming conventions -- Use `cuds_object` as the argument name of your methods (not `entity`, `cuds`, `cuds_instance`...). -- The official spelling is `OSP-core` (as opposed to _osp core_, _OSP-Core_ or similar). +- Use `cuds_object` as the argument name of your methods (not `entity`, + `cuds`, `cuds_instance`...). +- 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](https://github.com/simphony), rather than creating a branch -from `dev`, you will have to fork the repository and create the Pull Request. +If you are not a member of the +[SimPhoNy organisation](https://github.com/simphony), rather than creating +a branch from `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](https://github.com/simphony/wrapper-development) repo. +For a sample wrapper, visit the +[wrapper_development](https://github.com/simphony/wrapper-development) repo. README files should include: - Information regarding the purpose of the wrapper and the backend used. @@ -108,6 +157,7 @@ README files should include: - 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](https://github.com/simphony/docs/issues), and we will look into it!. - - +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](https://github.com/simphony/docs/issues), and we will look into it!.