1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
=====
Usage
=====
To use Releases, mimic the format seen in `its own changelog
<https://raw.github.com/bitprophet/releases/main/docs/changelog.rst>`_ or in
`Fabric's changelog
<https://raw.github.com/fabric/fabric/main/sites/www/changelog.rst>`_.
Specifically:
* Install ``releases`` and update your Sphinx ``conf.py`` to include it in the
``extensions`` list setting: ``extensions = ['releases']``.
* Also set the ``releases_release_uri`` and ``releases_issue_uri`` top
level options - they determine the targets of the issue & release links
in the HTML output. Both must include a ``{number}`` slug (for use
with `str.format`) where the release/issue number should go; the older
``%s`` style is also acceptable.
* Alternately, if your project is hosted on Github, set the
``releases_github_path`` setting instead, to e.g.
``account/project``. Releases will then use an appropriate Github
URL for both releases and issues.
* If ``releases_release_uri`` or ``releases_issue_uri`` are *also*
configured, they will be preferred over ``releases_github_path``.
(If only one is configured, the other link type will continue using
``releases_github_path``.)
* See `Fabric's docs/conf.py
<https://github.com/fabric/fabric/blob/4afd33e971f1c6831cc33fd3228013f7484fbe35/docs/conf.py#L31>`_
for an example.
* You may optionally set ``releases_debug = True`` to see debug output
while building your docs.
* If your changelog includes "simple" pre-1.0 releases derived from a
single branch (i.e. without stable release lines & semantic versioning)
you may want to set ``releases_unstable_prehistory = True``.
* This is also useful if you've just imported a non-Releases changelog,
where your issues are all basic list-items and you don't want to go
through and add bug/feature/support/etc roles.
* See :ref:`the appropriate conceptual docs <unstable-prehistory>` for
details on this behavior.
* If your development branch which is linked to for unreleased changelog
items, does not match the current default (``master`` as of version 2.0,
to be changed to ``main`` in 3.0), you may override it via
``releases_development_branch``.
* Projects with a long history of major release versions may want to
specify which of them get 'unreleased' entries at the top of the
changelog; set ``releases_supported_versions`` to a list of major version
numbers, eg ``releases_supported_versions = [2, 3]`` to drop any "Next
1.x (feature|bugfix)" buckets.
* Create a Sphinx document named ``changelog.rst`` containing a bulleted list
somewhere at its topmost level.
* If you wish to use a different document name, use another config option
(as per previous bullet point), ``releases_document_name``. E.g.
``releases_document_name = "CHANGES"`` would cause Releases to mutate a
file called ``CHANGES.rst`` instead of ``changelog.rst``.
* It is possible to target multiple changelog files for mutation by setting
``releases_document_name`` to a list of strings instead of a single
string, e.g. ``releases_document_name = ['project_1/changelog',
'project_2/changes', 'changelog']``.
* Releases only modifies the bulleted list in these files and does not
touch other elements; this allows you to place paragraphs, comments etc
at the top (or bottom) of the document.
* List items are to be ordered chronologically with the newest ones on top.
* As you fix issues, put them on the top of the list.
* As you cut releases, put those on the top of the list and they will
include the issues below them.
* Issues with no releases above them will end up in a specially marked
"Unreleased" section of the rendered changelog.
* Bullet list items should use the ``support``, ``feature`` or ``bug``
roles to mark issues, or ``release`` to mark a release. These special roles
must be the first element in each list item.
* Line-items that do not start with any issue role will be considered bugs
(both in terms of inclusion in releases, and formatting) and, naturally,
will not be given a hyperlink.
* Issue roles are of the form ``:type:`number[ keyword]```. Specifically:
* ``number`` is used to generate the link to the actual issue in your issue
tracker (going by the ``releases_issue_uri`` option). It's used for both
the link target & (part of) the link text.
* If ``number`` is given as ``-`` or ``0`` (as opposed to a "real" issue
number), no issue link will be generated. You can use this for items
without a related issue.
* Keywords are optional and may be one of:
* ``backported``: Given on *support* or *feature* issues to denote
backporting to bugfix releases; such issues will show up in both
release types. E.g. placing ``:support:`123 backported``` in your
changelog below releases '1.1.1' and '1.2.0' will cause it to appear
in both of those releases' lists.
* ``major``: Given on *bug* issues to denote inclusion in feature,
instead of bugfix, releases. E.g. placing ``:bug:`22 major``` below
releases '1.1.1' and '1.2.0' will cause it to appear in '1.2.0'
**only**.
* ``(N.N+)`` where ``N.N`` is a valid release line, e.g. ``1.1`` or
``2.10``: Given on issues (usually *bugs*) to denote minimum release
line. E.g. when actively backporting most bugs to release lines 1.2,
1.3 and 1.4, you might specify ``:bug:`55 (1.3+)``` to note that bug
55 only applies to releases in 1.3 and above - not 1.2.
* A `semantic version range spec covering minor+major version numbers
<https://python-semanticversion.readthedocs.io/en/latest/reference.html#version-specifications-the-spec-class>`_
such as ``(<2.0)`` or ``(>=1.0,<3.1)``. A more powerful version of
``(N.N+)`` allowing annotation of issues belonging to specific major
versions.
.. note::
It is possible to give *both* a regular keyword
(``backported``/``major``) *and* a spec (``(N.N+)``/``(>=1.0)``) in
the same issue. However, giving two keywords or two specs at the same
time makes no sense & is not allowed.
* Regular Sphinx content may be given after issue roles and will be preserved
as-is when rendering. For example, in ``:bug:`123` Fixed a bug, thanks
`@somebody`!``, the rendered changelog will preserve/render "Fixed a bug,
thanks ``@somebody``!" after the issue link.
* Release roles are of the form ``:release:`number <date>```.
* You may place a comma-separated (whitespace optional) list of issue
numbers after the release role, and this will limit the issues included
in that release to that explicit list.
* Otherwise, releases include all relevant issues as outlined above and
in :doc:`/concepts`.
Then build your docs; in the rendered output, ``changelog.html`` should show
issues grouped by release, as per the above rules. Examples: `Releases' own
rendered changelog
<http://releases.readthedocs.io/en/latest/changelog.html>`_, `Fabric's
rendered changelog <http://www.fabfile.org/changelog.html>`_.
Optional styling additions
==========================
If you have any nontrivial changelog entries (e.g. whose description spans
multiple paragraphs or includes their own bulleted lists, etc) you may run into
`docutils' rather enthusiastic bulleted list massaging
<http://docutils.sourceforge.net/sandbox/html4strict/data/simple-lists.html>`_
which can then make your releases look different from one another.
To help combat this, it may be useful to add the following rule to the Sphinx
theme you're using::
div#changelog > div.section > ul > li > p:only-child {
margin-bottom: 0;
}
.. note::
Some themes, like `Alabaster <http://github.com/bitprophet/alabaster>`_,
may already include this style rule.
|
