| 1 |
Changelog Generation |
| 2 |
==================== |
| 3 |
|
| 4 |
Changelogs help document important changes. We use an updated version of |
| 5 |
gitchangelog_ to produce a nice Github Release page (or just generate a |
| 6 |
shell SVD-style document) using the gitchangelog-action_ in the Release |
| 7 |
workflow. |
| 8 |
|
| 9 |
.. _gitchangelog: https://github.com/sarnold/gitchangelog |
| 10 |
.. _gitchangelog-action: https://github.com/marketplace/actions/gitchangelog-action |
| 11 |
|
| 12 |
|
| 13 |
To generate a (full) changelog from the repository root, run: |
| 14 |
|
| 15 |
.. code-block:: bash |
| 16 |
|
| 17 |
(venv) $ gitchangelog > CHANGELOG.rst |
| 18 |
|
| 19 |
You can use ``gitchangelog`` to create the changelog automatically. It |
| 20 |
examines git commit history and uses custom "filters" to produce its |
| 21 |
output. The configuration for this is in the file ``.gitchangelog.rc``. |
| 22 |
|
| 23 |
To make your changelog even more useful/readable, you should use good |
| 24 |
commit messages and consider using the gitchangelog message modifiers. |
| 25 |
Since the ``.gitchangelog.rc`` is actually written in Python, it becomes |
| 26 |
quite dynamic, thus the configured modifiers and associated documentation |
| 27 |
are usually documented in the file itself (unless someone strips out all |
| 28 |
the comments). For this config, the message format uses 3 types of |
| 29 |
modifier:: |
| 30 |
|
| 31 |
Message Format |
| 32 |
ACTION: [AUDIENCE:] COMMIT_MSG [!TAG ...] |
| 33 |
|
| 34 |
Description |
| 35 |
ACTION is one of 'chg', 'fix', 'new' |
| 36 |
|
| 37 |
Is WHAT the change is about. |
| 38 |
|
| 39 |
'chg' is for refactor, small improvement, cosmetic changes... |
| 40 |
'fix' is for bug fixes |
| 41 |
'new' is for new features, big improvement |
| 42 |
|
| 43 |
AUDIENCE is optional and one of 'dev', 'usr', 'pkg', 'test', 'doc' |
| 44 |
|
| 45 |
Is WHO is concerned by the change. |
| 46 |
|
| 47 |
'dev' is for developers (API changes, refactors...) |
| 48 |
'usr' is for final users (UI changes) |
| 49 |
'pkg' is for packagers (packaging changes) |
| 50 |
'test' is for testers (test only related changes) |
| 51 |
'doc' is for doc guys (doc only changes) |
| 52 |
|
| 53 |
COMMIT_MSG is ... well ... the commit message itself. |
| 54 |
|
| 55 |
TAGs are additional adjective as 'refactor' 'minor' 'cosmetic' |
| 56 |
|
| 57 |
They are preceded with a '!' or a '@' (prefer the former, as the |
| 58 |
latter is wrongly interpreted in github.) Commonly used tags are: |
| 59 |
|
| 60 |
'refactor' is obviously for refactoring code only |
| 61 |
'minor' is for a very meaningless change (a typo, adding a comment) |
| 62 |
'cosmetic' is for cosmetic driven change (re-indentation, 80-col...) |
| 63 |
'wip' is for partial functionality but complete sub-functionality. |
| 64 |
|
| 65 |
Example: |
| 66 |
|
| 67 |
new: usr: support of bazaar implemented |
| 68 |
chg: re-indented some lines !cosmetic |
| 69 |
new: dev: updated code to be compatible with last version of killer lib. |
| 70 |
fix: pkg: updated year of license coverage. |
| 71 |
new: test: added a bunch of test around user usability of feature X. |
| 72 |
fix: typo in spelling my name in comment. !minor |
| 73 |
|
| 74 |
|
| 75 |
See the current `.gitchangelog.rc`_ in the repo for more details. |
| 76 |
|
| 77 |
Read more about gitchangelog_. |
| 78 |
|
| 79 |
.. _.gitchangelog.rc: https://github.com/VCTLabs/redis-ipc/blob/develop/.gitchangelog.rc |
| 80 |
.. _gitchangelog: https://github.com/sarnold/gitchangelog |
| 81 |
|
| 82 |
|
| 83 |
Git Tags |
| 84 |
-------- |
| 85 |
|
| 86 |
Git tags are a way to bookmark commits, and come in two varieties: |
| 87 |
lightweight and signed/annotated. Both signed and annotated tags |
| 88 |
contain author information and when used they will help organize the |
| 89 |
changelog. |
| 90 |
|
| 91 |
To create an annotated tag for a version ``0.1.1`` release: |
| 92 |
|
| 93 |
.. code-block:: bash |
| 94 |
|
| 95 |
$ git tag -a v0.1.1 -m "v0.1.1" |
| 96 |
|
| 97 |
Using tags like this will break the changelog into sections based on |
| 98 |
versions. If you forgot to make a tag you can checkout an old commit |
| 99 |
and make the tag (don't forget to adjust the date - you may want to |
| 100 |
google this...) |
| 101 |
|
| 102 |
|
| 103 |
Sections |
| 104 |
-------- |
| 105 |
|
| 106 |
The sections in the changelog are created from the git log commit |
| 107 |
messages, and are parsed using the regex defined in the |
| 108 |
``.gitchangelog.rc`` configuration file. |