From d5e9e8d37bd2556f154ec136f9c0dc206a52e35a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc=20Cornell=C3=A0?= <hello@mcornella.com>
Date: Tue, 6 Apr 2021 22:11:02 +0200
Subject: [PATCH] docs: document commit convention in CONTRIBUTING.md

---
 CONTRIBUTING.md | 120 ++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 110 insertions(+), 10 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index be67e93b0..b7db4f661 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,16 +11,23 @@ issues and pull requests. Please read them closely.
 Foremost, be so kind as to [search](#use-the-search-luke). This ensures any contribution
 you would make is not already covered.
 
-* [Issues](#reporting-issues)
-  * [You have a problem](#you-have-a-problem)
-  * [You have a suggestion](#you-have-a-suggestion)
-* [Pull Requests](#submitting-pull-requests)
-  * [Getting started](#getting-started)
-  * [You have a solution](#you-have-a-solution)
-  * [You have an addition](#you-have-an-addition)
-* [Information sources (_aka_ search)](#use-the-search-luke)
+<!-- TOC -->
 
-**BONUS:** [Volunteering](#you-have-spare-time-to-volunteer)
+- [CONTRIBUTING GUIDELINES](#contributing-guidelines)
+  - [Reporting Issues](#reporting-issues)
+    - [You have a problem](#you-have-a-problem)
+    - [You have a suggestion](#you-have-a-suggestion)
+  - [Submitting Pull Requests](#submitting-pull-requests)
+    - [Getting started](#getting-started)
+    - [You have a solution](#you-have-a-solution)
+    - [You have an addition](#you-have-an-addition)
+  - [Use the Search, Luke](#use-the-search-luke)
+  - [Commit Guidelines](#commit-guidelines)
+    - [Format](#format)
+    - [Style](#style)
+  - [Volunteer](#volunteer)
+
+<!-- /TOC -->
 
 ## Reporting Issues
 
@@ -117,7 +124,100 @@ and [create an issue](#reporting-issues) or [submit a PR](#submitting-pull-reque
 
 ----
 
-### You have spare time to volunteer
+## Commit Guidelines
+
+Oh My Zsh uses the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+specification. The automatic changelog tool uses these to automatically generate
+a changelog based on the commit messages. Here's a guide to writing a commit message
+to allow this:
+
+### Format
+
+```
+type(scope)!: subject
+```
+
+- `type`: the type of the commit is one of the following:
+
+  - `feat`: new features.
+  - `fix`: bug fixes.
+  - `docs`: documentation changes.
+  - `refactor`: refactor of a particular code section without introducing
+    new features or bug fixes.
+  - `style`: code style improvements.
+  - `perf`: performance improvements.
+  - `test`: changes to the test suite.
+  - `ci`: changes to the CI system.
+  - `build`: changes to the build system (we don't yet have one so this shouldn't apply).
+  - `chore`: for other changes that don't match previous types. This doesn't appear
+    in the changelog.
+
+- `scope`: section of the codebase that the commit makes changes to. If it makes changes to
+  many sections, or if no section in particular is modified, leave blank without the parentheses.
+  Examples:
+
+  - Commit that changes the `git` plugin:
+  ```
+  feat(git): add alias for `git commit`
+  ```
+
+  - Commit that changes many plugins:
+  ```
+  style: fix inline declaration of arrays
+  ```
+
+  For changes to plugins or themes, the scope should be the plugin or theme name:
+
+  - ✅ `fix(agnoster): commit subject`
+  - ❌ `fix(theme/agnoster): commit subject`
+
+- `!`: this goes after the `scope` (or the `type` if scope is empty), to indicate that the commit
+  introduces breaking changes.
+
+  Optionally, you can specify a message that the changelog tool will display to the user to indicate
+  what's changed and what they can do to deal with it. You can use multiple lines to type this message;
+  the changelog parser will keep reading until the end of the commit message or until it finds an empty
+  line.
+
+  Example (made up):
+
+  ```
+  style(agnoster)!: change dirty git repo glyph
+
+  BREAKING CHANGE: the glyph to indicate when a git repository is dirty has
+  changed from a Powerline character to a standard UTF-8 emoji. You can
+  change it back by setting `ZSH_THEME_DIRTY_GLYPH`.
+
+  Fixes #420
+
+  Co-authored-by: Username <email>
+  ```
+
+- `subject`: a brief description of the changes. This will be displayed in the changelog. If you need
+  to specify other details you can use the commit body but it won't be visible.
+
+  Formatting tricks: the commit subject may contain:
+
+  - Links to related issues or PRs by writing `#issue`. This will be highlighted by the changelog tool:
+    ```
+    feat(archlinux): add support for aura AUR helper (#9467)
+    ```
+
+  - Formatted inline code by using backticks: the text inbetween backticks will also be highlighted by
+    the changelog tool:
+    ```
+    feat(shell-proxy): enable unexported `DEFAULT_PROXY` setting (#9774)
+    ```
+
+### Style
+
+Try to keep the first commit line short. This is harder to do using this commit style but try to be
+concise and if you need more space, you can use the commit body. Try to make sure that the commit
+subject is clear and precise enough that users will know what change by just looking at the changelog.
+
+----
+
+## Volunteer
 
 Very nice!! :)