77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
# Adding change notes with your PRs
|
|
|
|
It is very important to maintain a log for news of how
|
|
updating to the new version of the software will affect
|
|
end-users. This is why we enforce collection of the change
|
|
fragment files in pull requests as per [Towncrier philosophy].
|
|
|
|
The idea is that when somebody makes a change, they must record
|
|
the bits that would affect end-users only including information
|
|
that would be useful to them. Then, when the maintainers publish
|
|
a new release, they'll automatically use these records to compose
|
|
a change log for the respective version. It is important to
|
|
understand that including unnecessary low-level implementation
|
|
related details generates noise that is not particularly useful
|
|
to the end-users most of the time. And so such details should be
|
|
recorded in the Git history rather than a changelog.
|
|
|
|
# Alright! So how do I add a news fragment?
|
|
|
|
To submit a change note about your PR, add a text file into the
|
|
`docs/changelog-fragments.d/` folder. It should contain an
|
|
explanation of what applying this PR will change in the way
|
|
end-users interact with the project. One sentence is usually
|
|
enough but feel free to add as many details as you feel necessary
|
|
for the users to understand what it means.
|
|
|
|
**Use the past tense** for the text in your fragment because,
|
|
combined with others, it will be a part of the "news digest"
|
|
telling the readers **what changed** in a specific version of
|
|
the library *since the previous version*. You should also use
|
|
[MyST Markdown] syntax for highlighting code (inline or block),
|
|
linking parts of the docs or external sites.
|
|
At the end, sign your change note by adding ```-- by
|
|
{user}`github-username``` (replace `github-username` with
|
|
your own!).
|
|
|
|
Finally, name your file following the convention that Towncrier
|
|
understands: it should start with the number of an issue or a
|
|
PR followed by a dot, then add a patch type, like `feature`,
|
|
`bugfix`, `doc`, `misc` etc., and add `.md` as a suffix. If you
|
|
need to add more than one fragment, you may add an optional
|
|
sequence number (delimited with another period) between the type
|
|
and the suffix.
|
|
|
|
# Examples for changelog entries adding to your Pull Requests
|
|
|
|
File `docs/changelog-fragments.d/112.doc.md`:
|
|
|
|
```md
|
|
Added a `{user}` role to Sphinx config -- by {user}`webknjaz`
|
|
```
|
|
|
|
File `docs/changelog-fragments.d/105.feature.md`:
|
|
|
|
```md
|
|
Added the support for keyboard-authentication method
|
|
-- by {user}`Qalthos`
|
|
```
|
|
|
|
File `docs/changelog-fragments.d/57.bugfix.md`:
|
|
|
|
```md
|
|
Fixed flaky SEGFAULTs in `pylibsshext.channel.Channel.exec_command()`
|
|
calls -- by {user}`ganeshrn`
|
|
```
|
|
|
|
```{tip}
|
|
See `pyproject.toml` for all available categories
|
|
(`tool.towncrier.type`).
|
|
```
|
|
|
|
|
|
[MyST Markdown]:
|
|
https://myst-parser.rtfd.io/en/latest/syntax/syntax.html
|
|
[Towncrier philosophy]:
|
|
https://towncrier.rtfd.io/en/actual-freaking-docs/#philosophy
|