blob: 7a19e14776671c364260e0b31c317b99a9caaeee (
plain)
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
|
Change fragments
================
Every breaking change to Edify's public surface lands with a **change fragment**
in this directory. Fragments are the single source of truth for the CHANGELOG and
the upgrade guide: the release generator (``tools/changes.py``) concatenates them
into both outputs, then deletes them.
There is no external changelog tooling — the format is a small stdlib-parseable
INI, and the generator is a single stdlib script.
File format
-----------
One file per breaking change, named ``<fragment-id>.rst`` where ``<fragment-id>``
sorts into the order the fragment should appear in the release notes (for
example ``0010-char-class-escape.rst``). The file is an INI document with a single
``[change]`` section:
.. code-block:: ini
[change]
anchor = char-class-escape
heading = Character-class escaping is the minimal correct form
before = any_of_chars('#?!@$%^&*-') -> [\#\?!@$%\^\&\*\-]
after = any_of_chars('#?!@$%^&*-') -> [#?!@$%^&*-]
context = Only backslash, closing bracket, first-position caret, and interior
dash are escaped inside a character class; every other metacharacter is a
literal. Match behavior is unchanged.
Fields
------
``anchor`` (required)
The frozen ``.. _<anchor>:`` label the upgrade-guide section carries. The
deprecation-warning URL for this change ends in ``#<anchor>``.
``heading`` (required)
The one-line human title of the change.
``before`` / ``after`` (optional)
A before/after pair. Include both or neither. Rendered as a literal block when
present.
``context`` (required)
One or two sentences explaining what changed and what the caller should do.
May span multiple indented lines.
Release flow
------------
On release, ``tools/changes.py`` slots each fragment into the matching section of
``CHANGELOG.rst`` and the active upgrade guide in fragment-id order, then removes
the fragment files. Adding a fragment is the only step a contributor takes; the
generator does the rest.
|
