From 6395bfaf6ba97ff2ccc080866c7aaed97e1c1238 Mon Sep 17 00:00:00 2001 From: "Benjamin E. Coe" Date: Sat, 23 Mar 2019 09:15:13 -0700 Subject: [PATCH] docs: get text back in alignment with RFC-2119, eliminate some ambiguity in spec (#133) --- content/next/index.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/content/next/index.md b/content/next/index.md index b4576ec..aecc546 100644 --- a/content/next/index.md +++ b/content/next/index.md @@ -2,7 +2,7 @@ draft: true --- -# Conventional Commits 1.0.0-beta.2 +# Conventional Commits 1.0.0-beta.4 ## Summary @@ -33,7 +33,8 @@ consumers of your library: 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in semantic versioning). 1. **BREAKING CHANGE:** a commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning). A BREAKING CHANGE can be part of commits of any _type_. -1. Others: commit _types_ other than `fix:` and `feat:` are allowed, for example [commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) (based on the [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. +1. Others: commit _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. + We also recommend `improvement` for commits that improve a current implementation without adding a new feature or fixing a bug. Notice these types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE).
@@ -66,23 +67,27 @@ see the issue for details on the typos fixed fixes issue #12 ``` + ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). -1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by a colon and a space. +1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed + by an OPTIONAL scope, and a REQUIRED terminal semicolon and space. 1. The type `feat` MUST be used when a commit adds a new feature to your application or library. 1. The type `fix` MUST be used when a commit represents a bug fix for your application. -1. An optional scope MAY be provided after a type. A scope is a phrase describing a section of the codebase enclosed in parenthesis, e.g., `fix(parser):` -1. A description MUST immediately follow the type/scope prefix. -The description is a short description of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string._ +1. A scope MAY be provided after a type. A scope MUST consist of a noun describing a + section of the codebase surrounded by parenthesis, e.g., `fix(parser):` +1. A description MUST immediately follow the space after the type/scope prefix. +The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. -1. A footer MAY be provided one blank line after the body. - The footer SHOULD contain additional issue references about the code changes (such as the issues it fixes, e.g.,`Fixes #13`). -1. Breaking changes MUST be indicated at the very beginning of the footer or body section of a commit. A breaking change MUST consist of the uppercase text `BREAKING CHANGE`, followed by a colon and a space. +1. A footer of one or more lines MAY be provided one blank line after the body. The footer MUST contain meta-information +about the commit, e.g., related pull-requests, reviewers, breaking changes, with one piece of meta-information +per-line. +1. Breaking changes MUST be indicated at the very beginning of the body section, or at the beginning of a line in the footer section. A breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon and a space. 1. A description MUST be provided after the `BREAKING CHANGE: `, describing what has changed about the API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ -1. The footer MUST only contain `BREAKING CHANGE`, external links, issue references, and other meta-information. 1. Types other than `feat` and `fix` MAY be used in your commit messages. +1. The units of information that make up conventional commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase. ## Why Use Conventional Commits @@ -97,7 +102,7 @@ The description is a short description of the code changes, e.g., _fix: array pa ### How should I deal with commit messages in the initial development phase? -We recommend that you proceed as if you're an already released product. Typically *somebody*, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. +We recommend that you proceed as if you've already released the product. Typically *somebody*, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### Are the types in the commit title uppercase or lowercase? @@ -165,7 +170,7 @@ Configurable and usable for PHP projects as a composer dependency or usable glob * [massive.js](https://github.com/dmfay/massive-js): A data access library for Node and PostgreSQL. * [electron](https://github.com/electron/electron): Build cross-platform desktop apps with JavaScript, HTML, and CSS. * [scroll-utility](https://github.com/LeDDGroup/scroll-utility): A simple to use scroll utility package for centering elements, and smooth animations -* [Blaze UI](https://github.com/BlazeUI/blaze): Framework-free open source modular toolkit. +* [Blaze UI](https://github.com/BlazeUI/blaze): Framework-free open source UI toolkit. * [Monica](https://github.com/monicahq/monica): An open source personal relationship management system. * [mhy](https://mhy.js.org): 🧩 A zero-config, out-of-the-box, multi-purpose toolbox and development environment.