We will do all that we can to keep the productivity of ourselves, and others, as high as possible -- Uncle Bob
These guidelines are based on Building a strong community Github documentation and intend to promote a better collaboration.
Issue and pull request templates should drive reporters to give all the necessary information to help reviewers.
Import the pull request template and issue template into .github folder in your repository root directory.
Multiple issue templates are prefered over single issue templates in order to specify required information for each type of issue.
Import the following issue templates into .github/ISSUE_TEMPLATE/ folder in your repository root directory:
Issue and pull request templates should contains title (h2) and description using html comment.
Preferred:
## Description
<!-- A clear and concise description of what the bug is. -->
## How to reproduce it
<!-- Steps to reproduce the behavior. -->
...Not Preferred:
**Describe the bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
...Templates should promote a high contribution quality by referring contributing guidelines.
Preferred:
> Please fill out this template when filing an issue. It is based on [Excelsior Family Github guidelines](https://github.com/ExcelsiorFamily/github-guidelines).
>
> This template intends to describe a bug report. If you are describing a non existing feature, please use the [feature request template](https://github.com/ExcelsiorFamily/github-guidelines/issues/new?template=feature-request.md).
* [ ] I've read, understood, and done my best to follow the [CONTRIBUTING guidelines](/CONTRIBUTING.md).
## Description
<!-- A clear and concise description of what the bug is. -->
## How to reproduce it
<!-- Steps to reproduce the behavior. -->
...Not Preferred:
## Description
<!-- A clear and concise description of what the bug is. -->
## How to reproduce it
<!-- Steps to reproduce the behavior. -->
...Labels should help contributors and reviewers to evaluate effort for a specific issue or pull request.
GitHub labels should define immutable informations about issues, in order to avoid non-updated scenarios. States should be defined in project section.
Preferred:
- Type: Feature
- Severity: LowNot Preferred:
- WorkInProgress
- CriticalColors should help contributors and reviewers to quickly and visually identify the effort to be done. It is better to use similar color styling accross categories for a consistent and stronger visual identification. Colors should be variants of Red-Orange-Green to provide a sense of priority. Red being the ones that require the most attention. Green being the ones that require little attention.
Preferred:
Severity: LowSeverity: MediumChange: MinorChange: Medium
Not Preferred:
Severity: LowSeverity: MediumChange: MinorChange: Medium
Labels should be regrouped into categories to provide consistent information about every issue. Issues cannot have more than one label from the same category.
Preferred:
- Type: Documentation
- Severity: Medium
- Change: MinorNot Preferred:
- Question
- Feature
- DocumentationPro tip: GitHub orders labels aphabetically, so following this format allows to keep categories dislayed in the same order accross every issues.
Type labels should be used to define the type of task done inside the issue:
(#00cc41)
Type: Feature: The issue is the development of a new feature of your project(#ff0000)
Type: Bug: The issue is an identified bug that needs to be fixed(#ffe700)
Type: Enhancement: The issue is a suggestion of enhancement to your project(#c3b2ef)
Type: Documentation: The issue is the creation or refinement of a document.
Severity labels are mostly used for bug-related issues. It allows to identify the critical aspects of the work implied inside the issue:
(#000000)
Severity: Blocker: The issue is blocking an impending release(#ff4000)
Severity: Critical: The issue causes data loss, crashes or hangs salt processes, makes the system unresponsive, etc(#ff8100)
Severity: High: The issue reports incorrect functionality, bad functionality, a confusing user experience, etcSeverity: Strong: The issue concerns changes to the core areas of the projectSeverity: Medium: The issue reports cosmetic items, formatting, spelling, colors, etcSeverity: Low: The issue concerns a new feature or any addition to the project.
Type of change labels are only used for pull requests. They give information about the effort needed to review a pull request:
Change: Minor: Less than 64 lines changed, or less than 8 core lines changedChange: Medium: Less than 256 lines changed, or less than 64 core lines changedChange: Master: More than 256 lines changed, or more than 64 core lines changedChange: Expert: Needs specialized, in-depth review.
Pro Tip: We strongly recommend to define core areas to help define the estimated effort.