Workflow

To start working with us, please follow these simple steps:

1. Join GitHub.
2. Check out our repositories and open issues.
3. Join our Slack board.
4. Join the #oss-community and leave a short message about yourself. Please include (1) your relevant skills and experience level, (2) your GitHub username, (3) your email address (e.g., for calendar invitations), and (4) the repositories or issues you are most interested in. If you can't decide, no problem, just indicate that you are open to work on anything and we will suggest some issues for you.
5. Once we have added you to our GitHub organization, you can assign yourself to an issue.
6. Please carefully read the guidelines below, as well as any relevant language-specific guidelines in this section.
7. Start coding!

Privacy note

If you do not want to share your GitHub username and/or your email address in the public channel, please send a direct message to a project lead instead.

Always work on issues

If you want to propose code changes and there is no corresponding issue available, please make sure to open an issue first and get some feedback from project leads. This is to avoid the frustration of putting in work for nothing in case the project leads had other plans.

One-time contributors

If you like, you can skip steps 3. to 5. and raise pull requests from forks. Note, however, that some CI workflows may not (yet) be fully supported for pull requests raised from forks.

Guidelines

For your contributions, please follow the guidelines laid out below to the best of your ability.

Beginners

If you don't have a lot of experience with this sort of workflow, the guidelines in this section may seem overwhelming. But please don't worry! We will guide you through the process and you will soon get the hang of it. And please don't worry about making 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! :)

Communication

Please use the comment functions available on GitHub to discuss issues and pull requests. For all other communications please refer to the communication channels listed in the contact section. In particular, use the chat to discuss project ideas.

Submitting issues

Please use each project's GitHub issue tracker to:

• propose features
• report bugs
• find issues to work on
• discuss existing issues

As an example, you can find this project's issue tracker here.

When submitting new issues to propose features or report bugs, please choose the most appropriate template, if available, then follow the instructions in the template.

You don't need to add 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 relevant context (links, screenshots, etc.) to allow others to start working on them. For bug reports, it is essential that they include reproducible examples.

Here and here are some resources to help you get started on writing good issues.

Branching model

All of our projects are version-controlled via Git and codebases are hosted on GitHub. Please refer to appropriate documentation and tutorials if you are not familiar with them.

To keep track our project histories clean, we follow a slightly modified version of the GitHub Flow Branching model. What this means is that code changes are always merged into protected branches via pull requests that will undergo one or more rounds of review and testing. The schema below visualizes this process.

1. Create a "feature branch" from the dev branch; use the feature/my-feature naming pattern to name your feature branch, e.g., feature/update-docs; make sure the dev branch is up to date before creating the feature branch!
2. Commit code changes to address the issue you are working on
3. Push the feature branch to the remote and create a pull request in GitHub
4. Address any comments added during code review by pushing additional commits (there may be multiple rounds of reviews)
5. Once all issues are resolved, code owners will merge the feature branch into the dev branch using the "squash merging" method

Default branch

dev is the default branch for all projects in pre-release state, i.e., those with version numbers below v1.0.0. Upon release, main becomes the default branch, and semantic versioning is strictly adhered by.

Substantial changes

If your proposed changes will be substantial, try to split up the work into multiple feature branches. This makes reviewing easier, helps to keep the project history clean and may better guard against code regression. A rule of thumb is that you should be able to adequately summarize your changes with 50 characters.

If your changes are becoming more substantial than you anticipated, you can request that the branch be "rebase merged" instead of "squash merged". However, we will only do so if you have exactly one clean commit for each semantic work package and each commit message follows the conventional commit specifications. You can use git rebease --interactive to clean up your feature branch.

Feature branches unstable

All feature branches are to be considered unstable, i.e., their history may change at any time, even after being pushed to the remote. Therefore, do not work on feature branches without clearly communicating with the people who have created them.

Commit messages

Generally, no specific formatting of individual commit messages is required when working on feature branches. However, your pull request titles should always follow the Conventional Commits specification. The same is true for individual commit messages if you are requesting that your feature branch be "rebase merged" (see info box "Substantial changes" above).

Conventional Commits help to increase consistency, simplify maintenance and enable automated versioning and change log generation. Their general structure is as follows:

<type>(optional scope): <description>  # not more than 50 characters!!!

[optional body]

[optional footer]

Please keep the title line short (50 characters or less). If you want to get more descriptive, you can use the optional body. Please use the footer only to signify breaking changes, by adding BREAKING CHANGE to the start of the footer and describing why/what breaks. You can use multiple lines for body and footer, but please keep each line to 100 characters or less. For smaller projects such as most of ours, use of scope is not recommended.

Depending on the changes, we would kindly request you to 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.

Linting commit messages

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 a dedicated linter. More information can also be found in this blog post.

Filing pull requests

The following pull request template will be successively added to all repositories. Until that is the case, you can already make use of it by self-reviewing your pull requests according to the checklist and descriptions.

All Contributors

The All Contributors bot may not be available in all repositories yet. In that case, please ignore the last bullet point.

Pull request template

Description

Please include a summary of the change and the relevant issue(s) it resolves, if any (otherwise delete that line). If the PR addresses more than one issue, please add multiple lines, each starting with 'Fixes #'. In the summary, list any dependencies that are required for this change. Please use bullet points for the description. Please also include relevant motivation and context briefly if not already covered in the corresponding issue(s). For very trivial issues that are duly explained by the PR title, a description can be omitted (in that case, please delete the placeholder bullet point).

Fixes #(issue number)

Checklist

Please go through the following checklist to ensure that your change is ready for review. Please do not forget to double check the list after you have modified your PR, e.g., if you have added commits to address reviewer comments or to fix failing automated checks. Please check items also if they do not apply to your change, e.g., if your change does not require an update of the user-facing documentation, then still check the box. Generally, PRs are only reviewed when all boxes are ticked off and all automated checks pass (use the comment section below if you believe that your PR is ready to be merged even though not all boxes were ticked off).

• My code follows the contributing guidelines of this project, including, in particular, with regard to any style guidelines
• The title of my PR complies with the Conventional Commits specification; in particular, it clearly indicates that a change is a breaking change
• I acknowledge that all my commits will be squashed into a single commit, using the PR title as the commit message
• I have performed a self-review of my own code
• I have commented my code in hard-to-understand areas
• I have updated the user-facing documentation to describe any new or changed behavior
• I have added type annotations for all function/class/method interfaces or updated existing ones
• I have provided appropriate documentation (e.g., Google-style Python docstrings or JSDoc block tags) for all functions/classes/methods or updated existing ones
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have not reduced the existing code coverage
• I have asked the @all-contributors bot to acknowledge my contributions by commenting on this PR with a request of the form @all-contributors please add @YOUR_GH_HANDLE for TYPE_1, TYPE_2, ..., where TYPE_1 etc. refer to contribution types supported by the All Contributors Specification OR I do not want my contributions to be acknowledged by All Contributors

Comments

If there are unchecked boxes in the list above, but you would still like your PR to be reviewed or considered for merging, please describe here why boxes were not checked. For example, if you are positive that your commits should not be squased when merging, please explain why you think the PR warrants or requires multiple commits to be added to the history.