Note By interacting with @svengreb projects, organizations, and their communities you agree to abide to its code of conduct and follow general open source contribution guidelines and etiquettes!
We’re excited that you’re interested in contributing to the project! Please take a moment to read the guidelines in order to make the contribution process easy and effective for everyone involved. Following these guidelines helps to communicate that you respect the time of the members managing and developing this project. In return, they will reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
As for everything else in the project, contributions are governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to a project member or volunteer.
As an open source project we love to receive contributions from the community! There are many ways to contribute, from writing- and improving documentations and guides, reporting bugs, and submitting enhancement suggestions which can be incorporated into the code base through pull requests. The development workflow and process uses GitHub “Issues“ and “Pull Requests“ to track and manage contributions. The respective issue and pull request templates of a repository help to create contributions in the right form and also serve as a good starting point.
Before you continue with these contribution guidelines we highly recommend to read the GitHub‘s awesome “Open Source Guides“, especially the chapter about how to make open source contributions.
Some open source projects are larger and might consist of many repositories and are designed to be very modular. Please make sure to determine the correct repository before you continue! Contributions are welcome in their respective repositories. This helps project members, volunteers and contributors to process every contribution faster without organization overhead.
A bug is a demonstrable problem that is caused by the code in the repository. This section guides you through submitting a bug report. Following these guidelines helps project members and volunteers to understand your report, reproduce the behavior, find related reports and fix or resolve the cause.
- Use the GitHub issue search — check if a similar issue has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one, but only if you can add new or otherwise helpful information or context. Submitting a comment that reflects already known information or is only intended to show that you are also affected (“me too“ or “+1“ comments) only create notifications noise and increases the maintenance overhead for the project members and overall time until a solution can be provided. If you find a closed issue that seems like it is the same problem that you are experiencing, open a new issue and mention the already existing issue since closed issues are no longer monitored and processed.
- Check if the problem has already been fixed — try to reproduce it using the latest version of the project or the
mainrepository branch which contains the latest development state and might already include required code changes. - Isolate the problem — ideally create a MCVE to help project members to reproduce the problem behavior.
Please always provide as much detail and context as possible, e.g. your configuration and environment, and at least fill out and stick to the respective issue template, the information it asks for helps project members to understand the whole context, reproduce the problem and resolve issues faster.
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible.
- Attach files like screenshots or videos if appropriate which show you following the described steps and clearly demonstrate the problem.
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/paste snippets. If you are providing snippets in the issue, use Markdown code blocks or attach files to the issue.
Do NOT report security vulnerabilities in public issues! Please only contact one of the project members in a responsible manner to help project members to process and resolve it, working towards a coordinated disclosure. We will assess the issue as soon as possible on a best-effort basis and will give you an estimate for when we have a fix and release available for an public disclosure.
This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines helps project members and volunteers to understand your suggestion, discuss and process it.
- Use the GitHub issue search — check if a similar issue has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one, but only if you can add new or otherwise helpful information or context. Submitting a comment that reflects already known information or is only intended to show that you are also affected (“me too“ or “+1“ comments) only create notifications noise and increases the maintenance overhead for the project members and overall time until a solution can be provided. If you find a closed issue that seems like it is the enhancement that you want to suggest, open a new issue and mention the already existing issue since closed issues are no longer monitored and processed.
- Check if the enhancement has already been implemented — use the latest version of the project or the
mainrepository branch, which contains the latest development state, to ensure that the feature or improvement is not already available. - Optionally provide a reduced showcase, if possible — creating a MCVE helps project members to understand the goal quicker and maybe reuse the provided changes.
Before creating enhancement suggestions, please check if your idea fits with the scope and always provide as much detail and context as possible. Fill out and stick to the respective issue template, the information it asks for helps project members to understand the whole context, discuss it and process issues faster.
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible and provide use cases.
- Provide examples to demonstrate the need of an enhancement. Include links to files or GitHub projects, or copy/paste snippets. If you are providing snippets in the issue, use Markdown code blocks or attach files to the issue.
- Describe the current behavior and explain which behavior you expected to see instead and why.
- Explain why this enhancement would be useful to most users.
- Optionally list other projects where this enhancement exists or, if appropriate, attach files like screenshots, videos or animated GIFs showing the suggested enhancement.
This section guides you through submitting an pull request. Following these guidelines helps project members and volunteers to better understand your contribution, discuss and process it. Please suggest an enhancement or report a bug first before embarking on any significant pull request (e.g. implementing features, refactoring code, fixing a bug), otherwise you risk spending your time working on something that the maintainers might not want to merge into the project.
Before submitting a pull request, please check if it fits the project scope and always provide as much detail and context as possible. Fill out and stick to the respective issue template, the information it asks for helps project members to understand the whole context, discuss it and process contributions faster.
- Use a clear and descriptive title for the pull request to identify the contribution.
- Do not include issue numbers in the pull request title but add it to the top of the description like shown in the pull request template. This will enable the use of GitHub‘s issue keyword feature to link to specific enhancement suggestions or bug reports.
- Attach files like screenshots, videos or animated GIFs, if appropriate, that clearly demonstrate the change.
- Make sure to follow the project style guides.
- Remain focused in scope and avoid to include unrelated commits.
- Features and improvements should be accompanied with tests and documentation. If the pull request improves the performance consider to include a benchmark test, optimally including a chart.
- Lint and test before submitting your changes.
- Make sure to create the pull request from a topic branch.
All pull requests must be send against the main branch - Please make sure to read the branch organization section below for details about the branching model before submitting a pull request.
The documentation consists of user guides, specifications that serve as core references and dedicated documentations for each project.
You can help to improve these documents by making them more coherent, consistent and readable, adding missing information, correcting factual errors, fixing typos, and bringing them up-to-date when there are differences to the latest versions and development states. This can be done by submitting an enhancement suggestion and then opening a pull request for it.
The project uses the GitHub Flow branching model. The repository consists of the main core branch with an infinite development lifecycle. The source code of Git‘s HEAD in this branch contains the latest development state and reflects all tagged release versions.
All pull requests for limited development lifecycle story/topic branches must be send against the main branch.
Some issues are created with missing information, are not reproducible, or plain invalid. You can help to make it easier for project members and volunteers to understand and resolve them faster since handling issues takes a lot of time that could rather be spend on writing code and other changes.
We‘re always looking for more opinions on discussions in issues and pull request reviews which is a good opportunity to influence the future direction of the project.
Larger and major open source projects have their own style guides, a set of standards and conventions for the writing and design of code, documentations and Git []1 commit messages. It is much easier to understand content and a large code base when it is written with a consistent style. A style guide establishes and enforces style to improve the intelligibility and communication within a project community. It ensures consistency and enforces best practice in usage and language composition.
Therefore the project adheres to several style guides to ensure good quality and ensure to keep these standards for the future of the project. The listed style guides are used in all projects:
- Markdown Style Guide
- JavaScript Style Guide
- Git Style Guide — A well-crafted Git commit message is the best way to communicate context about a change to the maintainers. The code will tell what changed, but only the commit message can properly tell why. Re-establishing the context of a piece of code is wasteful. We can‘t avoid it completely, so our efforts should go to reducing it as much as possible. The style guide assumes that you are familiar with the GitHub Flow branching model.
Other style guides are in use depending on the project context like the programming language(s) and tools. Details about these varying style guides can be found in the corresponding documentations of the respective projects.
The project follows the Semantic Versioning Specification (SemVer). We release patch versions for bug fixes, minor versions for enhancements like new features and improvements, and major versions for any backwards incompatible changes. Deprecation warnings for breaking changes are introduced in a minor version so that users can learn about the upcoming changes and migrate their code in advance. Every significant change is at least documented in the changelog of the respective project, but will also be announced through the project‘s infrastructure and community platforms.
A Minimal, Complete, and Verifiable Example.
When reporting a bug, sometimes even when suggesting enhancements, the issue can be processed faster if you provide code for reproduction. That code should be…
- …minimal — use as little code as possible that still produces the same behavior
- …complete — provide all parts needed to reproduce the behavior
- …verifiable — test the code you‘re about to provide to make sure it reproduces the behavior
A MCVE is a common practice for large development communities and platforms like Stack Overflow and sometimes it is also called SSCCE, a Short, Self Contained, Correct (Compilable), Example.
The recommended way for GitHub based projects is to create a MCVE as Codespaces, Gist, or new repository, but you can also attach it to issues and pull requests as file(s), use any free code (snippet) or file hosting service like Codesandbox or paste the code in Markdown code blocks into the issue.
The more code there is to go through, the less likely developers can understand your enhancement or find the bug. Streamline your example in one of two ways:
- Restart from scratch — Create new code, adding in only what is needed to demonstrate the behavior and also useful if you can‘t post the original code publicly for legal, personal or ethical reasons.
- Divide and conquer — When you have a small amount of code, but the source of the bug is entirely unclear, start removing code a bit at a time until the problem disappears – then add the last part back and document this behavior to help developers to trace and debug faster.
Minimal does not mean terse, don‘t sacrifice communication to brevity. Use consistent naming and indentation following the style guides of the project, and include comments if needed to explain portions of the code.
Make sure all resources and code necessary to reproduce the behavior is included. The problem might not be in the part you suspect it is, but another part entirely.
To entirely understand your bug report or enhancement, developers will need to verify that it exists:
- Follow the contribution guidelines regarding the description and details — Without information developers won‘t be able to understand and reproduce the behavior.
- Eliminate any issues that are not relevant — Ensure that there are no compile-time errors.
- Make sure that the example actually reproduces the problem — Sometimes the bug gets fixed inadvertently or unconsciously while composing the example or does not occur when running in a “fresh“ development environment.
Copyright © 2016-present Sven Greb
Thanks for the inspirations to GitHub‘s Open Source Guides and various contribution guides of large open source projects like React, Atom, PhotoPrism and Ruby on Rails.