Some rules and advices for developers who want to contribute to these or their projects and keep them human friendly.
Git is used as the version control system. Each developer must be familiar with the basic functionality of git before contributing to the project. If necessary, look at this guide.
Conventional Commits specification shall be used for commit messages. Read the specification carefully and use this compact list of conventional commit types to help you. You'll quickly get used to it!
Common types of commit messages:
Type | Meaning |
---|---|
docs: | Documentation only changes. |
feat: | A new feature. |
fix: | A bug fix. |
refactor: | A code change that neither fixes a bug nor adds a feature. |
perf: | A code change that improves performance. |
style: | Changes that do not affect the meaning of the code. |
Basic rules:
In the project, the following branch types are recommended:
Type | Branch | Meaning |
---|---|---|
Stable | stable | Accepts merges from Working and Hotfixes |
Working | master | Accepts merges from Features/Issues and Hotfixes |
Features/Issues | topic/* | Always branch off HEAD of Working |
Hotfix | hotfix/* | Always branch of Stable |
topic
can be defined (but not limited to) as feat
, fix
and docs
. Each commit to the stable
branch must contain a tag with the following format: <version>-stable
. See the article for detailed information.
Warning: branch naming rules from the article are NOT used in this project – only branching rules.
Sometimes it might be a little tricky to update the Stable branch.
It should be updated with the latest stable features.
git merge -s ours origin/stable
.git push
.chore/update-stable-branch
to stable
.It is recommended to have pre-commit installed and configured in order to keep the repository and its code organized.
pre-commit
is a tool that runs some hooks (wait for it) before the commit, such as black
, flake8
or any other hook you wish.
Usually it should be already inside the requirements-dev.txt
file and therefore you could just run pip install -U -r requirements-dev.txt
. However, if you want to manually install it, run pip install pre-commit
.
After running either of the commands above, run pre-commit install
, with or without --allow-missing-config
. Terminal should return pre-commit installed at .git/hooks/pre-commit
.
Optionally, you can run against all files by using
pre-commit run --all-files
. You will get a 'Failed' or 'Passed' status.
Black can be run manually by usingpython -m black ./
If there are weird errors appearing, you can try topre-commit autoupdate
Note: You need to configure a .pre-commit-config.yaml
before you can use pre-commit. Here you can define all tests and linters you would like to use.
Here's an example:
repos:
- repo: https://github.com/psf/black
rev: 21.9b0
hooks:
- id: black
- repo: https://gitlab.com/pycqa/flake8
rev: 3.9.2
hooks:
- id: flake8
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.0.1
hooks:
- id: check-added-large-files
- id: end-of-file-fixer
- id: trailing-whitespace
For versioning of the packages Semantic Versioning (SemVer) is used. Read the specification carefully and take a look at the how-to guide to SemVer.
Try to follow the PEP8. In summary:
Import order: Built-ins, Third-parties, Locals. First the import ...
then the
from ... import ...
Prioritize Absolute Imports over Relative Imports (e.g., import pkg_a.utils
)
Use as
to reduce the verbosity (e.g., import pkg_a.pkg_b.pkg_c.utils as pkg_utils
)
Prioritize import ... as ...
for modules and packages
Avoid from ... import ...
. But if needed, use it for importing specific functions/classes from a module/package
Leave __init__.py
empty unless needed (e.g., making a function from a module accessible from the package. Even on these cases, prioritize absolute imports)
flake8 is used for style guide checking. Usually, CI build of the projects runs linting with flake8 and the build will not be succeeded without corresponding styling. Before committing the code, don't forget to check styling locally. Various python IDEs also support the integration of flake8. Standard flake8 configuration for this project is as follows:
[flake8]
# Matching the black line length (default 88)
max-line-length = 88
max-complexity = 10
extend-ignore =
# See https://github.com/PyCQA/pycodestyle/issues/373
E203,
F811,
exclude =
.flake8,
.git,
.venv*,
.env*,
.bkp*,
__pycache__,
# Add your folders to ignore here
build/,
output/,
bin/,
dist/,
In this project reStructuredText (reST) Docstring Format is used, according to proposal in PEP 287. See the example of such formatting here. A docstring for each function and class are recommended.
Each repository must have a README with at least:
Take a look at the READMEs of other repos if you need some inspiration! :D
Each repository can have a CONTRIBUTING with the necessary information for new developers to be able to contribute with the Project.