We might need to record some guidelines for this (maybe, in a follow-up).

Yes, I think we can refine this more in the contributing docs? For now, I wanted to make some kind of update here and keep it pretty simple.

Yes, I was imagining it'd be just linked here.

I think this is okay for now? But if you have some idea on where/how to link, I'm happy to include a small change.

In aiohttp, we have a bit of explanation right in the PR template: aio-libs/aiohttp#11320. However, it's also possible to add a Markdown link to RTD (or GH README preview), just like in the following checkbox one line below.

I was overthinking this one. The PR template now has a link to the changelog.d/README.md. Maybe there's a better way to do it, but I linked directly to https://github.com/jazzband/pip-tools/blob/main/changelog.d/README.md

My thought is that we may tweak the doc over time, so linking to the published RTD site could be out of date.

Sure, no rush to make it perfect in this PR.

Did you decide not to follow my boilerplate? Any thoughts? Concrete fragment examples to show? These could be a few of the fragments you're adding in this PR copied into this doc.
Also, let's mention the possibility of bylines.

First, regarding bylines: yes, I'll add that for sure. More thoughts on that topic to follow (I want to rewrite the past entries too).

I was trying to balance concerns between trying to keep things similar to what you have in other projects, but also produce a document which gets new contributors to the instructions quickly. I'm a little concerned about the example from cheroot -- I think that for a new contributor that doc is a bit intimidating and gives too much detail about the rationale for Towncrier and changelogs up front.

My preference is for this doc to read primarily as a "how to", and for the motivation behind it to be separated out. (Similar to diataxis, but simply as sections within a doc.)

I think we can reintroduce all of the elments I removed in a sub-section, keeping the start of the doc short and recipe-like.
Would you be okay with the content flowing as follows?

## Adding Change Notes with PRs

<mostly the currently proposed "how to" content + mention of adding a byline>

### Categories

The change categories are defined as follows:

- `bugfix:` A bug fix for something we deemed an improper undesired behavior that got corrected in the release to match pre-agreed expectations.
- ... <list follows>

Sometimes it's not clear which category to use for a change. Do your best and a maintainer can discuss this with you during review.

### Example Change Notes

<copy from cheroot example>

### Rationale

When somebody makes a change, they must record the bits that would affect end-users only including information that would be useful to them. ... <content from cheroot example follows>

We write change notes in the past tense because this suits the users who will be reading these notes.
Combined with others, the notes will be a part of the "news digest" telling the readers what **changed** in a specific version of the library since the previous version.

<anything else from the cheroot doc which I've missed probably goes here>

I like this idea. I was mostly writing those explanations in isolation with no feedback loop, having been tired of re-explaining how people should author their notes. And so I've been dragging this document around across projects.
I think it's imperfect, and I'd like to improve it. I've been thinking of how to integrate some ideas from https://redhat-documentation.github.io/supplementary-style-guide/#release-notes and lurking into the release notes channel in the Write The Docs Slack, but haven't gotten to it yet.

So if you manage to make it more friendly, I'd love to copy it back into other projects. Making sphinxcontrib-towncrier was one of the sides of me attempting to improve authoring change logs.

### Example Change Notes

<copy from cheroot example>

I think you should copy some of the actual change notes you're adding in this PR. I've been doing that, and it feels more immersive when yarl fragment examples talk about yarl and aiohttp examples talk about aiohttp.

I'd be nice to improve my bot eventually to be able to help with change note authoring, similar to CPython's blurb-it. But that's a separate endeavor.

Yes, I think we can refine this more in the contributing docs? For now, I wanted to make some kind of update here and keep it pretty simple.

First, regarding bylines: yes, I'll add that for sure. More thoughts on that topic to follow (I want to rewrite the past entries too).

I was trying to balance concerns between trying to keep things similar to what you have in other projects, but also produce a document which gets new contributors to the instructions quickly. I'm a little concerned about the example from cheroot -- I think that for a new contributor that doc is a bit intimidating and gives too much detail about the rationale for Towncrier and changelogs up front.

My preference is for this doc to read primarily as a "how to", and for the motivation behind it to be separated out. (Similar to diataxis, but simply as sections within a doc.)

I think we can reintroduce all of the elments I removed in a sub-section, keeping the start of the doc short and recipe-like.
Would you be okay with the content flowing as follows?

## Adding Change Notes with PRs

<mostly the currently proposed "how to" content + mention of adding a byline>

### Categories

The change categories are defined as follows:

- `bugfix:` A bug fix for something we deemed an improper undesired behavior that got corrected in the release to match pre-agreed expectations.
- ... <list follows>

Sometimes it's not clear which category to use for a change. Do your best and a maintainer can discuss this with you during review.

### Example Change Notes

<copy from cheroot example>

### Rationale

When somebody makes a change, they must record the bits that would affect end-users only including information that would be useful to them. ... <content from cheroot example follows>

We write change notes in the past tense because this suits the users who will be reading these notes.
Combined with others, the notes will be a part of the "news digest" telling the readers what **changed** in a specific version of the library since the previous version.

<anything else from the cheroot doc which I've missed probably goes here>

This pattern is a bit new for me as I typically use RST and the title is coming from the Sphinx's directive entirely (and the version is setuptools-scm-made in those cases), but perhaps, we could take this opportunity to prefix the date with clearer text:

(we probably don't need an else-branch with an "actually released on " wording, right?)

By the way, have you tested a regular non---draft run locally? Does it produce satisfactory output?

I like the "Generated for preview on..." style; adding that to my current changeset!

I did a non-draft run pretty early in this work, so it easily could have drifted. I'll double-check it after this next batch of changes.

I think this deserves to be a title:

Alternatively, at least make it more distinct:

Having it as plain text doesn't help people notice that there are multiple categories rather than just a wall of text, in my view: https://pip-tools--2203.org.readthedocs.build/en/2203/changelog/#unreleased-changes.

I wanted these to be titles, but I resisted in order to stay consistent with the past changelogs.
I'll update them all to match, but I'll do it in a dedicated commit so that it's easy to revert if we'd rather save this for later.

I'm not too worried about temporary inconsistency. My preference is to just have the final template in right away. But I'll let you decide if you want to postpone this.

I made a change where I made the old sections into headers. So the names of sections may be inconsistent but the styling will be consistent.

<!-- new stuff -->
### Features
...
### Contributor-facing changes
...
<!-- old stuff -->
### Major Changes
...
### Other Changes
...

This is fine. The old categories are different and it's okay to skip normalizing them.

I'm uneasy about dropping the "PRs and issues" prefix. Having this start with a paren enables weird sequences when the change notes end with a period.

You can see multiple sequences like . (# @ https://pip-tools--2203.org.readthedocs.build/en/2203/changelog/#unreleased-changes which is what I was trying to avoid by (1) placing these refs on separate lines (so weird things in notes wouldn't make it look odd), and (2) would work with both single-liners and multi-paragraph blurbs.

Having no prefix only works when somebody forgets to end their phrase with a period.

Besides, commit and arbitrary refs have the same level of importance and I think they should follow the same style.

Yeah, I'm easily convinced on this. I don't mind the . (# formatting, but it is a little weird looking.

I'll adjust (back) to "PRs and issues".

Thanks!

I've since learned that it's possible to have something like

def setup(app: Sphinx) -> dict[str, bool | str]:
    """Register project-local Sphinx extension-API customizations.

    :param app: Initialized Sphinx app instance.
    :returns: Extension metadata.
    """
    if IS_RELEASE_ON_RTD:
        app.tags.add("is_release")

    return {
        'parallel_read_safe': True,
        'parallel_write_safe': True,
        'version': release,
    }

at the very bottom.

I think this can work better with typing, plus would let us drop linting suppressions.

This is pretty neat; I never knew you could put this hook into conf.py. I wonder if some of the custom plugin cases I've bumped into could be replaced with this... 🤔

Oh yeah, I've been doing this for years. Just keep in mind that conf.py is a special case and there be dragons (I was once very confused when I placed some directive classes into it and couldn't understand why that was exploding — this was when I was first writing that sphinxcontrib-towncrier extension in-tree). But most of the time, it works just fine. For more complex things, I still tend to move code into dedicated modules in-project.

Some examples include https://github.com/cherrypy/cheroot/blob/587d1fa5e19eb1337d2b9c22995783761628c4b1/docs/spelling_stub_ext.py vs. https://github.com/ansible/awx-plugins/blob/c4180cd22bc6b83750d3256892c38f342eb1e9c5/docs/conf.py#L236-L272.