Skip to content

README.md

Latest commit

 

History

History
390 lines (269 loc) · 15.5 KB

README.md

File metadata and controls

390 lines (269 loc) · 15.5 KB

Github Guidelines

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.

Table of Contents

Issue & Pull Request Template

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 Over Single Issue Template

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 & Pull Request Expectation

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

...

Promoting A High Contribution Quality

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. -->

...

Git Commit Messages

Git commit messages should help reviewers to do better reviews.

Short Commit Messages

Short commit messages should help reviewers to quickly understand what has been done. It should be short, clear and written at the present tense and imperative mood.

Preferred:

- Add get user feature.
- Update navigation storyboard.

Not Preferred:

- Added get user feature.
- Updates navigation storyboard.

Issue Reference

Referencing issue in git commit messages should help anyone to track progress on a specific issue. Git commit messages should always reference issues at the end.

Preferred:

- Improve cache management. Related to #42.
- Remove unused ViewController method. Related to #1024.

Not Preferred:

- Improve cache management.
- #1024 Remove unused ViewController method.

Commit Nature

Emojis should help reviewers to quickly and visually identify the nature of the commit. For clear visual identification start the commit message with an applicable emoji:

  • 🎨 :art: when improving the format/structure of the code
  • 🐎 :racehorse: when improving performance
  • 🚱 :non-potable_water: when plugging memory leaks
  • 📝 :memo: when writing docs
  • 🐛 :bug: when fixing a bug
  • 🔥 :fire: when removing code or files
  • 💚 :green_heart: when fixing the CI build
  • ✅ :white_check_mark: when adding tests
  • 🔒 :lock: when dealing with security
  • ⬆️ :arrow_up: when upgrading dependencies
  • ⬇️ :arrow_down: when downgrading dependencies
  • 👕 :shirt: when removing linter warnings

Milestone

Milestones should be based on iterative development and produce incremental builds. It enforces Agile methodology and promote continuous integration and deployment. It allows you to follow overall progress and create changelogs based on opened/closed issues.

Incremental Title

Milestones should be described as increment based on software version.

Preferred:

Milestones:

- 1.1.0
- 1.2.0
- 1.3.0
- 1.4.0

Not Preferred:

Milestones:

- Backlog
- Ice Box
- Release 1.0
- Release 2.0

Pro tip: when closing a milestone, a git tag using software version should be created.

Short Iterative Due Date

Milestones must have short due dates to define small increment and should only be closed when progress is at 100%, meaning that all issues and pull requests related to it are closed. If you do not consider an issue to be necessarily closed to finish your current milestone then it should be moved to another one.

Preferred:

Milestones:

- 1.1.0 - Closed 4 weeks ago
- 1.2.0 - Closed 2 weeks ago
- 1.3.0 - Closed 1 day ago
- 1.4.0 - Due by June 8, 2018

Not Preferred:

Milestones:

- Backlog - No due date
- Ice Box - No due date
- Version 1.0 - Due by September 1, 2019
- Version 2.0 - Due by September 1, 2022

Pro tip: when closing a milestone, webhooks can be used to automatically create a release flow.

Github Issue And Pull Request Priority

Milestones should drive development for contributors and help them to focus on most priority issues and pull requests. Priorization should be based on comparaison and it's up to maintainers.

Pro tip: labels should help maintainers to compare issues and pull requests easily.

Label

Labels should help contributors and reviewers to evaluate effort for a specific issue or pull request.

Immutablity

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: Low

Not Preferred:

- WorkInProgress
- Critical

Colors

Colors 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:

  • #c3b2ef Severity: Low
  • #00cc41 Severity: Medium
  • #c3b2ef Change: Minor
  • #00cc41 Change: Medium

Not Preferred:

  • #c3b2ef Severity: Low
  • #c3b2ef Severity: Medium
  • #00cc41 Change: Minor
  • #00cc41 Change: Medium

Categories

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: Minor

Not Preferred:

- Question
- Feature
- Documentation

Pro tip: GitHub orders labels aphabetically, so following this format allows to keep categories dislayed in the same order accross every issues.

Type

Type labels should be used to define the type of task done inside the issue:

  • #00cc41 (#00cc41) Type: Feature: The issue is the development of a new feature of your project
  • #ff0000 (#ff0000) Type: Bug: The issue is an identified bug that needs to be fixed
  • #ffe700 (#ffe700) Type: Enhancement: The issue is a suggestion of enhancement to your project
  • #c3b2ef (#c3b2ef) Type: Documentation: The issue is the creation or refinement of a document.

Severity

Severity labels are mostly used for bug-related issues. It allows to identify the critical aspects of the work implied inside the issue:

  • #000000 (#000000) Severity: Blocker: The issue is blocking an impending release
  • #ff4000 (#ff4000) Severity: Critical: The issue causes data loss, crashes or hangs salt processes, makes the system unresponsive, etc
  • #ff8100 (#ff8100) Severity: High: The issue reports incorrect functionality, bad functionality, a confusing user experience, etc
  • #ffe700 (#ffe700) Severity: Strong: The issue concerns changes to the core areas of the project
  • #00cc41 (#00cc41) Severity: Medium: The issue reports cosmetic items, formatting, spelling, colors, etc
  • #c3b2ef (#c3b2ef) Severity: Low: The issue concerns a new feature or any addition to the project.

Type Of Change

Type of change labels are only used for pull requests. They give information about the effort needed to review a pull request:

  • #c3b2ef (#c3b2ef) Change: Minor: Less than 64 lines changed, or less than 8 core lines changed
  • #00cc41 (#00cc41) Change: Medium: Less than 256 lines changed, or less than 64 core lines changed
  • #ffe700 (#ffe700) Change: Master: More than 256 lines changed, or more than 64 core lines changed
  • #ff0000 (#ff0000) Change: Expert: Needs specialized, in-depth review.

Pro Tip: We strongly recommend to define core areas to help define the estimated effort.

CHANGELOG

CONTRIBUTING.md

Every GitHub repository must have a CONTRIBUTING.md file. It allows maintainers to expose the project's context and contributing guidelines.

Before I Get Started

A good CONTRIBUTING.md should make any contributor feel comfortable to get his hands on the project. Therefore, it is imperative to give an overview of your project. The first thing that should appear in this file is a Before I Get Started section. This section aims at exposing the project's scope, its files organisation, dependencies and information about design.

First, the scope should be about how the project was defined, meaning what kind of project you have to deal with. Is it a regular application? Is it an SDK? Is it using a specific technology? etc.

The section should desribe briefly the files organisation to help the contributor understand where to look for what he wants or where to add a file.

Then, it should explain to the contributor the dependencies the project has. It means that is should describe all external dependencies that are imported into the project, but also if the project is meant to be used by others.

Finally, it should give some information about the design decisions and link to the Architectural Decision Records section of your project.

How To Contribute

Once the context and scope of the projects are clear, the reader should have information about how to contribute to the project, depending on the type of task he wants to do. Each type of tasks needs to have a context, some information about what to do before that type of thask and finally how to contribute to such task.

There are three types of contribution possible: bug report, suggesting a new feature, suggesting a technical enhancement.

Before Contributing

Before anything else a contributor must be told to do at least two things :

  • Determine which repository the task should be done in
  • Check if a an issue is already open about this task

Contributing

For any contribution to be efficient, guidelines need to be set in order to always have the needed informations.

A contribution should always be tracked as a GitHub issue. Those issues should be created using a Template.

Pull Requests

Contributors should be informed and guided by templates on how to create pull requests for their work. See Pull Requests Template section for more information about this.

Styleguides

The Styleguides section should give information about the project's overall styleguide. This means it should give styling recommendations about :

  • Git commits
  • Coding
  • Documentation

It should contain clear guidelines and link to more complete documention and/or examples.

Issue And Pull Request Labels

The final section to be in the CONTRIBUTING.md should be about issues and pull requests labels to allow anyone to use them properly when contributing but also to identify them properly when looking for information. It should be stored inside a table for more readability.

Preferred:

| Label name | Description |
| --- | --- |
| `Type: Feature` | The issue is the development of a new feature of your project |
| `Type: Bug` | The issue is an identified bug that needs to be fixed |

Not Preferred:

- `Feature`: new feature of a project
- `Bugs`: identified bug that needs to be fixed

Resources