Skip to content

Code formatting with black and isort #202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 7, 2022
Merged

Code formatting with black and isort #202

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 84 additions & 34 deletions docs/source/contribute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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:

<figure style="display: table; text-align:center; margin-left: auto; margin-right:auto">

Expand All @@ -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.
Expand All @@ -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!.