We are using Git, GitHub and Git Flow.
Note: If you are a beginner and do not have a lot of experience with this sort of workflow, please do not feel overwhelmed. We will guide you through the process until you feel comfortable using it. And do not worry about mistakes either - everybody does them. Often! Our project layout makes it very very hard for anyone to cause irreversible harm, so relax, try things out, take your time and enjoy the work! :)
Please use each project's GitHub issue tracker to:
- find issues to work on
- report bugs
- propose features
- discuss future directions
Please choose a template when submitting an issue: choose the Bug report template only when reporting bugs; for all other issues, choose the Feature request template. Please follow the instructions in the template.
You do not need to worry about adding labels or milestones for an issue, the project maintainers will do that for you. However, it is important that all issues are written concisely, yet with enough detail and with proper references (links, screenshots, etc.) to allow other contributors to start working on them. For bug reports, it is essential that they include reproducible examples.
Please do not use the issue tracker to ask usage questions, installation problems etc., unless they appear to be bugs.
To make it easier for everyone to maintain, read and contribute to the code, as well as to ensure that the code base is robust and of high quality, we would kindly ask you to stick to the following guidelines for code style.
- Please use a recent version of Python 3 (3.7.4+)
- Please try to conform to the used code, docstring and commenting style within a project to maintain consistency
- Please use the following linters (use default settings unless otherwise
stated):
shellcheck,flake8
In an effort to increase consistency, simplify maintenance and enable automated change logs, we would like to kindly ask you to write semantic commit messages, as described in the Conventional Commits specification.
The general structure of Conventional Commits is as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer]Depending on the changes, please use one of the following type prefixes:
| Type | Description |
|---|---|
| build | The build type (formerly known as chore) is used to identify development changes related to the build system (involving scripts, configurations or tools) and package dependencies. |
| ci | The ci type is used to identify development changes related to the continuous integration and deployment system - involving scripts, configurations or tools. |
| docs | The docs type is used to identify documentation changes related to the project - whether intended externally for the end users (in case of a library) or internally for the developers. |
| feat | The feat type is used to identify production changes related to new backward-compatible abilities or functionality. |
| fix | The fix type is used to identify production changes related to backward-compatible bug fixes. |
| perf | The perf type is used to identify production changes related to backward-compatible performance improvements. |
| refactor | The refactor type is used to identify development changes related to modifying the codebase, which neither adds a feature nor fixes a bug - such as removing redundant code, simplifying the code, renaming variables, etc. |
| revert | For commits that revert one or more previous commits. |
| style | The style type is used to identify development changes related to styling the codebase, regardless of the meaning - such as indentations, semi-colons, quotes, trailing commas and so on. |
| test | The test type is used to identify development changes related to tests - such as refactoring existing tests or adding new tests. |
In order to ensure that the format of your commit messages adheres to the Conventional Commits specification and the defined type vocabulary, you can use the dedicated linter. More information about Conventional Commits can also be found in this blog post.
Here is a check list that you can follow to make sure that code merges happen smoothly:
- Open an issue first to give other contributors a chance to discuss the proposed changes (alternatively: assign yourself to one of the existing issues)
- Clone the repository, create a feature branch off of the default branch (never commit changes to protected branches directly) and implement your code changes
- If applicable, update relevant sections of the documentation
- Add or update tests; untested code will not be merged; refer to the guidelines above for details
- Ensure that your coding style is in line with the guidelines described above
- Ensure that all the checks configured in the continuous integration (CI) pipeline pass without issues
- If necessary, clean up excessive commits with
git rebase; cherry-pick and merge commits as you see fit; use concise and descriptive commit messages - Push your clean, tested and documented feature branch to the remote; make sure the CI pipeline passes
- Issue a pull request against the default branch; follow the instructions in the template; importantly, describe your changes in detail, yet with concise language, and do not forget to indicate which issue(s) the code changes resolve or refer to; assign a project maintainer to review your changes