Skip to content

Commit 474f318

Browse files
myiimyii
committed
docs(contributing): convert to .rst and move to docs subdir
* Update link in `README.rst`
1 parent 8de7804 commit 474f318

File tree

3 files changed

+144
-91
lines changed

3 files changed

+144
-91
lines changed

‎CONTRIBUTING.md

Lines changed: 0 additions & 89 deletions
This file was deleted.

‎docs/CONTRIBUTING.rst

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
How to contribute
2+
=================
3+
4+
This document will eventually outline all aspects of guidance to make your contributing experience a fruitful and enjoyable one.
5+
What it already contains is information about *commit message formatting* and how that directly affects the numerous automated processes that are used for this repo.
6+
7+
Commit message formatting
8+
-------------------------
9+
10+
Automation of multiple processes
11+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12+
13+
This formula uses `semantic-release <https://github.com/semantic-release/semantic-release>`_ for automating numerous processes such as bumping the version number appropriately, creating new tags/releases and updating the changelog.
14+
The entire process relies on the structure of commit messages to determine the version bump, which is then used for the rest of the automation.
15+
16+
Full details are available in the upstream docs regarding the `Angular Commit Message Conventions <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines>`_.
17+
The key factor is that the first line of the commit message must follow this format:
18+
19+
.. code-block::
20+
21+
type(scope): subject
22+
23+
24+
* E.g. ``docs(contributing): add commit message formatting instructions``.
25+
26+
Besides the version bump, the changelog and release notes are formatted accordingly.
27+
So based on the example above:
28+
29+
..
30+
31+
.. raw:: html
32+
33+
<h3>Documentation</h3>
34+
35+
* **contributing:** add commit message formatting instructions
36+
37+
38+
* The ``type`` translates into a ``Documentation`` sub-heading.
39+
* The ``(scope):`` will be shown in bold text without the brackets.
40+
* The ``subject`` follows the ``scope`` as standard text.
41+
42+
Linting commit messages in Travis CI
43+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
44+
45+
This formula uses `commitlint <https://github.com/conventional-changelog/commitlint>`_ for checking commit messages during CI testing.
46+
This ensures that they are in accordance with the ``semantic-release`` settings.
47+
48+
For more details about the default settings, refer back to the ``commitlint`` `reference rules <https://conventional-changelog.github.io/commitlint/#/reference-rules>`_.
49+
50+
Relationship between commit type and version bump
51+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52+
53+
This formula applies some customisations to the defaults, as outlined in the table below,
54+
based upon the `type <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type>`_ of the commit:
55+
56+
.. list-table::
57+
:name: commit-type-vs-version-bump
58+
:header-rows: 1
59+
:stub-columns: 0
60+
:widths: 1,2,3,1,1
61+
62+
* - Type
63+
- Heading
64+
- Description
65+
- Bump (default)
66+
- Bump (custom)
67+
* - ``build``
68+
- Build System
69+
- Changes related to the build system
70+
- –
71+
-
72+
* - ``chore``
73+
- –
74+
- Changes to the build process or auxiliary tools and libraries such as documentation generation
75+
- –
76+
-
77+
* - ``ci``
78+
- Continuous Integration
79+
- Changes to the continuous integration configuration
80+
- –
81+
-
82+
* - ``docs``
83+
- Documentation
84+
- Documentation only changes
85+
- –
86+
- 0.0.1
87+
* - ``feat``
88+
- Features
89+
- A new feature
90+
- 0.1.0
91+
-
92+
* - ``fix``
93+
- Bug Fixes
94+
- A bug fix
95+
- 0.0.1
96+
-
97+
* - ``perf``
98+
- Performance Improvements
99+
- A code change that improves performance
100+
- 0.0.1
101+
-
102+
* - ``refactor``
103+
- Code Refactoring
104+
- A code change that neither fixes a bug nor adds a feature
105+
- –
106+
- 0.0.1
107+
* - ``revert``
108+
- Reverts
109+
- A commit used to revert a previous commit
110+
- –
111+
- 0.0.1
112+
* - ``style``
113+
- Styles
114+
- Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
115+
- –
116+
- 0.0.1
117+
* - ``test``
118+
- Tests
119+
- Adding missing or correcting existing tests
120+
- –
121+
- 0.0.1
122+
123+
124+
Use ``BREAKING CHANGE`` to trigger a ``major`` version change
125+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
126+
127+
Adding ``BREAKING CHANGE`` to the footer of the extended description of the commit message will **always** trigger a ``major`` version change, no matter which type has been used.
128+
This will be appended to the changelog and release notes as well.
129+
To preserve good formatting of these notes, the following format is prescribed:
130+
131+
132+
* ``BREAKING CHANGE: <explanation in paragraph format>.``
133+
134+
An example of that:
135+
136+
.. code-block:: git
137+
138+
...
139+
140+
BREAKING CHANGE: With the removal of all of the `.sls` files under
141+
`template/package/`, this formula no longer supports the installation of
142+
packages.
143+

‎docs/README.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
================
21
template-formula
32
================
43

@@ -34,7 +33,7 @@ Contributing to this repo
3433

3534
**Commit message formatting is significant!!**
3635

37-
Please see `CONTRIBUTING <CONTRIBUTING.md>`_ for more details.
36+
Please see `CONTRIBUTING <CONTRIBUTING.rst>`_ for more details.
3837

3938

4039
Available states

0 commit comments

Comments
 (0)