Debian Codegraph @

docs/source/dev/generate-changelog.rst

raw
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.