|
| 1 | +.. _contributing: |
| 2 | + |
| 3 | +How to contribute |
| 4 | +================= |
| 5 | + |
| 6 | +This document will eventually outline all aspects of guidance to make your contributing experience a fruitful and enjoyable one. |
| 7 | +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. |
| 8 | +It also covers how to contribute to this *formula's documentation*. |
| 9 | + |
| 10 | +.. contents:: **Table of Contents** |
| 11 | + |
| 12 | +Overview |
| 13 | +-------- |
| 14 | + |
| 15 | +Submitting a pull request is more than just code! |
| 16 | +To achieve a quality product, the *tests* and *documentation* need to be updated as well. |
| 17 | +An excellent pull request will include these in the changes, wherever relevant. |
| 18 | + |
| 19 | +Commit message formatting |
| 20 | +------------------------- |
| 21 | + |
| 22 | +Since every type of change requires making Git commits, |
| 23 | +we will start by covering the importance of ensuring that all of your commit |
| 24 | +messages are in the correct format. |
| 25 | + |
| 26 | +Automation of multiple processes |
| 27 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 28 | + |
| 29 | +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. |
| 30 | +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. |
| 31 | + |
| 32 | +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>`_. |
| 33 | +The key factor is that the first line of the commit message must follow this format: |
| 34 | + |
| 35 | +.. code-block:: |
| 36 | +
|
| 37 | + type(scope): subject |
| 38 | +
|
| 39 | +
|
| 40 | +* E.g. ``docs(contributing): add commit message formatting instructions``. |
| 41 | + |
| 42 | +Besides the version bump, the changelog and release notes are formatted accordingly. |
| 43 | +So based on the example above: |
| 44 | + |
| 45 | +.. |
| 46 | +
|
| 47 | + .. raw:: html |
| 48 | + |
| 49 | + <h3>Documentation</h3> |
| 50 | + |
| 51 | + * **contributing:** add commit message formatting instructions |
| 52 | + |
| 53 | + |
| 54 | +* The ``type`` translates into a ``Documentation`` sub-heading. |
| 55 | +* The ``(scope):`` will be shown in bold text without the brackets. |
| 56 | +* The ``subject`` follows the ``scope`` as standard text. |
| 57 | + |
| 58 | +Linting commit messages in Travis CI |
| 59 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 60 | + |
| 61 | +This formula uses `commitlint <https://github.com/conventional-changelog/commitlint>`_ for checking commit messages during CI testing. |
| 62 | +This ensures that they are in accordance with the ``semantic-release`` settings. |
| 63 | + |
| 64 | +For more details about the default settings, refer back to the ``commitlint`` `reference rules <https://conventional-changelog.github.io/commitlint/#/reference-rules>`_. |
| 65 | + |
| 66 | +Relationship between commit type and version bump |
| 67 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 68 | + |
| 69 | +This formula applies some customisations to the defaults, as outlined in the table below, |
| 70 | +based upon the `type <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type>`_ of the commit: |
| 71 | + |
| 72 | +.. list-table:: |
| 73 | + :name: commit-type-vs-version-bump |
| 74 | + :header-rows: 1 |
| 75 | + :stub-columns: 0 |
| 76 | + :widths: 1,2,3,1,1 |
| 77 | + |
| 78 | + * - Type |
| 79 | + - Heading |
| 80 | + - Description |
| 81 | + - Bump (default) |
| 82 | + - Bump (custom) |
| 83 | + * - ``build`` |
| 84 | + - Build System |
| 85 | + - Changes related to the build system |
| 86 | + - – |
| 87 | + - |
| 88 | + * - ``chore`` |
| 89 | + - – |
| 90 | + - Changes to the build process or auxiliary tools and libraries such as |
| 91 | + documentation generation |
| 92 | + - – |
| 93 | + - |
| 94 | + * - ``ci`` |
| 95 | + - Continuous Integration |
| 96 | + - Changes to the continuous integration configuration |
| 97 | + - – |
| 98 | + - |
| 99 | + * - ``docs`` |
| 100 | + - Documentation |
| 101 | + - Documentation only changes |
| 102 | + - – |
| 103 | + - 0.0.1 |
| 104 | + * - ``feat`` |
| 105 | + - Features |
| 106 | + - A new feature |
| 107 | + - 0.1.0 |
| 108 | + - |
| 109 | + * - ``fix`` |
| 110 | + - Bug Fixes |
| 111 | + - A bug fix |
| 112 | + - 0.0.1 |
| 113 | + - |
| 114 | + * - ``perf`` |
| 115 | + - Performance Improvements |
| 116 | + - A code change that improves performance |
| 117 | + - 0.0.1 |
| 118 | + - |
| 119 | + * - ``refactor`` |
| 120 | + - Code Refactoring |
| 121 | + - A code change that neither fixes a bug nor adds a feature |
| 122 | + - – |
| 123 | + - 0.0.1 |
| 124 | + * - ``revert`` |
| 125 | + - Reverts |
| 126 | + - A commit used to revert a previous commit |
| 127 | + - – |
| 128 | + - 0.0.1 |
| 129 | + * - ``style`` |
| 130 | + - Styles |
| 131 | + - Changes that do not affect the meaning of the code (white-space, |
| 132 | + formatting, missing semi-colons, etc.) |
| 133 | + - – |
| 134 | + - 0.0.1 |
| 135 | + * - ``test`` |
| 136 | + - Tests |
| 137 | + - Adding missing or correcting existing tests |
| 138 | + - – |
| 139 | + - 0.0.1 |
| 140 | + |
| 141 | +Use ``BREAKING CHANGE`` to trigger a ``major`` version change |
| 142 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 143 | + |
| 144 | +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. |
| 145 | +This will be appended to the changelog and release notes as well. |
| 146 | +To preserve good formatting of these notes, the following format is prescribed: |
| 147 | + |
| 148 | +* ``BREAKING CHANGE: <explanation in paragraph format>.`` |
| 149 | + |
| 150 | +An example of that: |
| 151 | + |
| 152 | +.. code-block:: git |
| 153 | +
|
| 154 | + ... |
| 155 | +
|
| 156 | + BREAKING CHANGE: With the removal of all of the `.sls` files under |
| 157 | + `template package`, this formula no longer supports the installation of |
| 158 | + packages. |
| 159 | +
|
| 160 | +
|
0 commit comments