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