chore: Switch to Angular commit convention 🦆

Fixes #1673
styleguidist · Sep 2, 2020 · 4790f3f · 4790f3f
1 parent be90f3a
commit 4790f3f
Show file tree

Hide file tree

Showing 3 changed files with 106 additions and 40 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -65,5 +65,4 @@ jobs:
 
     - stage: release
       script:
-        - npm install --no-save conventional-changelog-eslint
         - npx semantic-release
diff --git a/docs/Maintenance.md b/docs/Maintenance.md
@@ -15,35 +15,119 @@ Help us develop and maintain Styleguidist:
 
 ## Commit message conventions
 
-We use [ESLint commit message conventions](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint).
+We use a simplified [Angular commit message conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit). This makes automated releases with [semantic-release](https://github.com/semantic-release/semantic-release) possible.
 
-Each commit looks like this:
+\*\*The main differences with the Angular convention is that all messages are capitalized. Commit messages are written for humans to read, so we should use text convention for humans, not for machines.
+
+Hovewer, we commit messages should follow a ceratain structure, so they semantic-release could generate nice human-readalbe changelogs.
+
+**The commit message** consists of a `header`, a `body`, and a `footer`:
 
 ```
-Tag: Short description (fixes #1234)
+<header>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The `header` is mandatory and must conform to the commit message header format described below.
 
-Longer description here if necessary
+The `body` optional but higly recommended for most commits, except very simple ones.
+
+The `footer` is optional.
+
+**The commit message header** looks like this:
+
+```
+<type>: <Short summary>
+  │       │
+  │       └─⫸ Summary in present tense. Capitalized. No period at the end.
+  │
+  └─⫸ Commit type: chore|docs|feat|fix|refactor|test
 ```
 
-The `Tag` is one of the following:
+The `<type>` and `<Short summary>` fields are mandatory.
+
+### Type
+
+Must be one of the following:
+
+- `chore` — configuration change, dependencies upgrade, and so on.
+- `docs` — changes to documentation only.
+- `feat` — a new feature.
+- `fix` — a bug fix.
+- `refactor` — a code change that neither fixes a bug nor adds a feature.
+- `test` — adding missing tests or correcting existing tests.
+
+### Short summary
+
+Use the summary field to provide a short description of the change.
+
+- use the imperative, present tense: “change” not “changed” nor “changes”;
+- always capitalize the first letter;
+- no dot (.) at the end.
+
+### Commit message body
+
+As in the summary, use the imperative, present tense: “fix” not “fixed” nor “fixes”, but put a dot (.) at the end of each sentence.
 
-- `Fix` — for a bug fix.
-- `Update` — for a backwards-compatible enhancement.
-- `New` — implemented a new feature.
-- `Breaking` — for a backwards—incompatible enhancement or feature.
-- `Docs` — changes to documentation only.
-- `Build` — changes to build process only.
-- `Upgrade` — for a dependency upgrade.
-- `Chore` — for refactoring, adding tests and so on (anything that isn’t user-facing).
+Explain the motivation for the change: why you are making it. You could include a comparison of the previous behavior with the new behavior to illustrate the impact of the change.
 
-If the commit doesn’t completely fix the issue, then use (`refs #1234`) instead of (`fixes #1234`).
+### Commit message footer
 
-Here are some good commit message summary examples:
+The footer could contain information about breaking changes, and is also the place to reference GitHub issues, and other pull requests that this commit closes or is related to.
 
 ```
-Build: Update Travis to only test Node 0.10 (refs #734)
-Fix: Semi rule incorrectly flagging extra semicolon (fixes #840)
-Upgrade: Esprima to 1.2, switch to using comment attachment (fixes #730)
+BREAKING CHANGE: <breaking change summary>
+<BLANK LINE>
+<breaking change description + migration instructions>
+<BLANK LINE>
+<BLANK LINE>
+Fixes #<issue number>
+```
+
+Breaking change section should start with the phrase `BREAKING CHANGE:` (with a `:` and a space at the end, you must use ALL CAPS — _sorry but life is full of pain_) followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.
+
+If the commit doesn’t completely fix the issue, then use (`Refs #1234`) instead of (`Fixes #1234`).
+
+### Commit messsage example
+
+````
+Fix: Fix missing FlowType enum values in prop description
+
+In ef4c109b, the file `PropsRenderer.js` (located at
+`src/client/rsg-components/Props/PropsRenderer.js`) was removed. In
+`PropsRenderer.js`, the `renderExtra` method checked whether `getType`
+for the argument to `renderExtra` was present:
+
+```es6
+function renderExtra(prop) {
+  const type = getType(prop);
+  if (!type) {
+    return null;
+  }
+  ...
+}
+```
+
+However, in ef4c109b, this method was replaced with `renderExtra.tsx`
+and the condition was changed to:
+
+```typescript
+export default function renderExtra(prop: PropDescriptorWithFlow): React.ReactNode {
+  const type = getType(prop);
+  if (!prop.type || !type) {
+    return null;
+  }
+````
+
+Unfortunately, this extra condition has resulted in this method always returning `null` for a Flow typed prop as `prop.type` is always `null` as `prop.type` is never set.
+
+This commit reverts the condition to what it was before the migration to TypeScript.
+
+Fixes #1234
+
 ```
 
 ## Pull requests
@@ -58,17 +142,17 @@ We’re doing automated releases with semantic-release. We’re using [milestone
 
 ### Patch releases
 
-Any commit of a `Fix` or `Update` types merged into the master branch, is published as a _patch_ release as soon as CI passes.
+Any commit of a `fix` type merged into the master branch, is published as a _patch_ release as soon as CI passes.
 
 ![](https://d3vv6lp55qjaqc.cloudfront.net/items/1T3v1z0c3f1I1E3l0B3s/patch-commit.png)
 
 ### Minor releases
 
-Any commit of a `New` type merged into the master branch, is published as a _minor_ release as soon as CI passes.
+Any commit of a `feat` type merged into the master branch, is published as a _minor_ release as soon as CI passes.
 
 ### Major releases
 
-Any commit of a `Breaking` type merged into the master branch, is published as a _major_ release as soon as CI passes.
+Any commit of a `feat` type with a breaking change section merged into the master branch, is published as a _major_ release as soon as CI passes.
 
 1. Merge all pull requests from a milestone. If a milestone has more than one pull request, they should be merged and released together:
    1. Create a new branch.
@@ -94,3 +178,4 @@ Here’s a [good example of a changelog](https://github.com/styleguidist/react-s
 
 - Information about pull request authors:<br> `(#1040 by @rafaesc)`
 - Open Collective link at the very top:<br> `👋 **[Support Styleguidist](https://opencollective.com/styleguidist) on Open Collective** 👋`
+```
diff --git a/release.config.js b/release.config.js