|
| 1 | +# Adding change notes with your PRs |
| 2 | + |
| 3 | +It is very important to maintain a log for news of how |
| 4 | +updating to the new version of the software will affect |
| 5 | +end-users. This is why we enforce collection of the change |
| 6 | +fragment files in pull requests as per [Towncrier philosophy]. |
| 7 | + |
| 8 | +The idea is that when somebody makes a change, they must record |
| 9 | +the bits that would affect end-users only including information |
| 10 | +that would be useful to them. Then, when the maintainers publish |
| 11 | +a new release, they'll automatically use these records to compose |
| 12 | +a change log for the respective version. It is important to |
| 13 | +understand that including unnecessary low-level implementation |
| 14 | +related details generates noise that is not particularly useful |
| 15 | +to the end-users most of the time. And so such details should be |
| 16 | +recorded in the Git history rather than a changelog. |
| 17 | + |
| 18 | +# Alright! So how do I add a news fragment? |
| 19 | + |
| 20 | +To submit a change note about your PR, add a text file into the |
| 21 | +`docs/changelog-fragments.d/` folder. It should contain an |
| 22 | +explanation of what applying this PR will change in the way |
| 23 | +end-users interact with the project. One sentence is usually |
| 24 | +enough but feel free to add as many details as you feel necessary |
| 25 | +for the users to understand what it means. |
| 26 | + |
| 27 | +**Use the past tense** for the text in your fragment because, |
| 28 | +combined with others, it will be a part of the "news digest" |
| 29 | +telling the readers **what changed** in a specific version of |
| 30 | +the library *since the previous version*. You should also use |
| 31 | +[MyST Markdown] syntax for highlighting code (inline or block), |
| 32 | +linking parts of the docs or external sites. |
| 33 | +At the end, sign your change note by adding ```-- by |
| 34 | +{user}`github-username``` (replace `github-username` with |
| 35 | +your own!). |
| 36 | + |
| 37 | +Finally, name your file following the convention that Towncrier |
| 38 | +understands: it should start with the number of an issue or a |
| 39 | +PR followed by a dot, then add a patch type, like `feature`, |
| 40 | +`bugfix`, `doc`, `misc` etc., and add `.md` as a suffix. If you |
| 41 | +need to add more than one fragment, you may add an optional |
| 42 | +sequence number (delimited with another period) between the type |
| 43 | +and the suffix. |
| 44 | + |
| 45 | +# Examples for changelog entries adding to your Pull Requests |
| 46 | + |
| 47 | +File `docs/changelog-fragments.d/112.doc.md`: |
| 48 | + |
| 49 | +```md |
| 50 | +Added a `{user}` role to Sphinx config -- by {user}`webknjaz` |
| 51 | +``` |
| 52 | + |
| 53 | +File `docs/changelog-fragments.d/105.feature.md`: |
| 54 | + |
| 55 | +```md |
| 56 | +Added the support for keyboard-authentication method |
| 57 | +-- by {user}`Qalthos` |
| 58 | +``` |
| 59 | + |
| 60 | +File `docs/changelog-fragments.d/57.bugfix.md`: |
| 61 | + |
| 62 | +```md |
| 63 | +Fixed flaky SEGFAULTs in `pylibsshext.channel.Channel.exec_command()` |
| 64 | +calls -- by {user}`ganeshrn` |
| 65 | +``` |
| 66 | + |
| 67 | +```{tip} |
| 68 | +See `pyproject.toml` for all available categories |
| 69 | +(`tool.towncrier.type`). |
| 70 | +``` |
| 71 | + |
| 72 | + |
| 73 | +[MyST Markdown]: |
| 74 | +https://myst-parser.rtfd.io/en/latest/syntax/syntax.html |
| 75 | +[Towncrier philosophy]: |
| 76 | +https://towncrier.rtfd.io/en/actual-freaking-docs/#philosophy |
0 commit comments