Separate deprecation and removal categories/fragment by default?

[abravalheri]

Right now towncrier creates a single changelog section for both removals and deprecations. The default section title is "Deprecations and Removals" and it is associated with the fragment type/suffix removal.

In #704, I have proposed to separate the categories for deprecation and removal fragments (ie. 2 sections and 2 fragment types).

The reasoning behind this proposal is that many projects usually treat them differently. Despite they being conceptually related, it is very common for projects to first announce deprecations in "non-breaking" releases and then in a "future breaking release" remove them. This happens for example using semver-ish version schemes.

For this kind of projects, it is useful to have 2 distinct categories for the following reasons:

1. It improves communication: The user can scan the changelog and quickly identify by the title of the section which are the breaking changes.
2. It improves automation: Some projects use tools to decide when to do a major/minor/patch level bump on the version, based on the type of fragments that have been comitted.

That said, not all projects use this kind of versioning schemes and/or automation, and the two concepts are indeed kind of related. Some people prefer less sections and fewer types of arguments.

So the idea of this discussion is to try to gauge the interest of the community for a possible change.

[adiroiban]

Many thanks for creating this discussion. Much appreciated.

---

I am ok with deprecations and removals... less is more :)

What I don't like, is the single .removal fragment. I feel like this is bad design.

[abravalheri]

Thanks @adiroiban . I don't know if I understood your point correctly when you say "single .removal fragment ... is a bad design" or if it was a bad choice of wording from my side.

What I mean is that right now (unless customised by the user) we have a single removal fragment that is "matched" against the section title "Deprecations and Removals" (other default fragments are "matched" against other sections).

So if you are writing a pull request with a deprecation to a project that does not customise the towncrier configuration and you want the fragment to end up in the section titled Deprecations and Removals, you will need to name your fragment XX.removal.rst (although you are not adding an actual removal).

So when I use the term "keep a single removal fragment" what I mean is to keep the current default behaviour that implies that people reporting deprecations should use the removal fragment.

(I am not proposing to change anything regarding the other default fragments like doc. These stay the same).

[adiroiban]

Yes. I consider the use of .removal file extension bad UI/design.

As you mentioned, we are using .removal even when we are only deprecating someting and not necesarily removing it. This can be confusing and counter intuitive.

You can argue that deprecating something is like planing for removal...so it can be included in the category of removal changes

[jaraco]

You can argue that deprecating something is like planing for removal...so it can be included in the category of removal changes

From a documentation standpoint, this rationale is reasonable, but the suitability breaks down when one has that infer the version bump from the scope of changes, it causes deprecations to trigger major version bumps, incorrectly indicating an incompatible change.

Without the ability to discern the difference between a breaking change and a deprecation, removal is overloaded. In the past, we've just put deprecations under .feature, but that confuses our users when the deprecations are described under features and there are never any deprecations under "... and Deprecations".

[jaraco]

The poll results, although a tiny sample, seem to suggest a supermajority prefers more fidelity for deprecations and removals. Can we consider that approach?

[adiroiban]

Hi Jason... I don't think that the poll results are relevant... 2 votes vs 1 vote.

But we can go with the benevolent dicator(s) approach here.

If the current active developer prefer separate categories, we can go with that.

My suggestion for default categories, in order of their appearance from top to bottom:

• .prelude , .highlight or some other name ... at the very top below the version number ... maybe without a category title
• .security -> Security changes
• .upgrade -> Upgrade notes
• .removal -> Breaking changes
• .feature -> New features
• .bugfix -> Defect fixes
• .deprecation -> Deprecation things that still work... but will be removed soon
• .misc

---

state of the art

Reno

Release notes should be grouped by type in the output document.

• New features

• Known issues

• Upgrade notes

• Security fixes

• Bugs fixes

• Other

---

semantic-releases I am not sure what categories they have

---

keep a changelog also has .security

---

Happy to check other similar tools and see what are their default values

[webknjaz]

@adiroiban wow, I just suggested prelude in pip-tools the other day: jazzband/pip-tools#2287.

I've been meaning to bring up refining the default categories too...
Here's a config I've been using in multiple places (@aio-libs, @ansible, @cherrypy) for a while: https://github.com/jazzband/pip-tools/blob/21c9b84199f777f589d9c5b190a1ee1a3d2d565f/towncrier.toml#L18-L67.

Notable highlights are not hiding misc, a clear separation of news for downstreams (packaging) and project contributors (contrib). Here's how they are explained: https://pip-tools.rtfd.io/en/stable/contributing/#adding-change-notes-with-prs.

Here's example renders: https://pip-tools.rtfd.io/en/latest/changelog/ / https://yarl.aio-libs.org/en/latest/changes/.

---

security seems important too (I often just post-edit the rendered file for this without that category). And also, I know that pip has a vendoring category.

[adiroiban]

I think there are 3 main use cases for Towncrier....

1. Open source libraries - targeted to external developers , not contributors
2. Open source or commercials end products - targeted to end users
3. Project contributors - to help them understand what other developers are doing

---

I see the release notes as targeted to end users ... that is, not targeted to the core dev team

I hope that we can find a good default for both cases ... without making it too complicated.

I don't want to add too many categories, as they can get confusing, I think that for the majoriy of the projects will want to keep things simple.

Projects can ignore some of these categories

---

We need to keep the following 5 sections for backward compatibilty: feature, bugfix, doc, removal, and misc.

---

Here is my suggestion for 8 sections (+1 kept only for backward compat):

• .highlight at the very top below the version number without a category title
• .security -> Security changes ... these can be bugfix or features ... but they need extra attention
• .upgrade -> Upgrade notes
• .removal or .breaking (I prefer .removal to help with backward compatibilty) -> Breaking changes
• .bugfix -> Defect fixes
• .feature -> New features
• .dev -> Docs, packaging, contrib, deprecation, planned removals
• .doc -> Kept for backward compatibility, but the documentation will recommned using .dev for new projects
• .misc -> No text ... mentioned only as links ... if you want to add text, use any of the other categories ... I am also using .ignore as an alias for this. .. or we can call it .none or anything else... I am not happy with .misc but I don't have a better name.... and we can keep it for backward compatibility

I bundled docs, packaging. contrib, deprecation, upstream, downstream ... etc into a single .dev category... and this category goes last and can be ignored by end users.

And if you are a contributor to the project, I think that you should be aware of all the dev related changes ... hence, a single category

---

Please send your suggestions and we can look to implement a new default configuration

[abravalheri]

Thank you very much @adiroiban for looking into this.

To be honest, my main concern is to separate the .removal or .breaking category from the .deprecation category. The reasoning is described in #704.

If your package offers an API, then .deprecation is a thing that will affect your users eventually. With that in mind it is good to communicate to them as early as possible what will happen (although it has not happened yet).

In that scenario .deprecation is not something that should be ignored by users (and it is often a thing they should keep an eye on).

[webknjaz]

@adiroiban

I don't think that .dev being mixed together works for me — the whole idea was keeping things separate. I also don't think that capping the default category list should happen. If a project doesn't use a category, it doesn't really matter that it's possible to use it — they can just skip it with no UX penalty.

FWIW, perhaps, it'd be a good idea to have a plugin interface for towncrier with the possibility for categories to come from them via hooks. This way, it'd be possible to create shareable collections of categories (and other settings!). And then, different communities could do something pip install towncrier-$ecosystem_name instead of trying to maintain a copy of the same exact setup across dozens of projects, while not relying on however the upstream would be maintaining the list of defaults. Although, one problem with that is checking for the fragments with GH Apps as those need to load said list and would be unwise to actually install+execute third-party plugins. Maybe, this is solvable through categories-in-entry-points, however.