Default `towncrier` configuration uses title `Deprecations and Removals` for `.removal.rst` files which clashes with `jaraco.develop.towncrier` assumptions

[abravalheri]

By default the section title associated with .removal.rst files is "Deprecations and Removals", however this bundles 2 distinct behaviours together according to https://semver.org:

• deprecations are introduced in minor version bumps
• removals are done in major version bumps.

This clashes with the assumptions in jaraco.develop.towncrier (and other projects using it like setuptools), which uses .removal.rst files for major version updates.

We are left with a dilemma:

• If we want a minor version bump, then we need to use a .feature.rst file. However this will add changelog lines like "Deprecated feature X" in the Features section. Meanwhile the Deprecations and Removals will not have any deprecations...
• If we want the deprecations to go to the Deprecations and Removals section, then we need to use the .removal.rst file. However, this will cause a major version bump (but it should be a minor version bump).

[abravalheri]

Also, should doc changes be related to a patch update instead of minor?

[webknjaz]

Last year, I've spent quite a lot of time thinking about Towncrier configs and came up with the following setup: https://github.com/aio-libs/yarl/blob/07f1fe9/towncrier.toml / https://yarl.aio-libs.org/en/latest/changes/#id78.

[jaraco]

I also don't like that .removal implies deprecation. I believe it's an oversight in the default behavior of towncrier.

I'm opposed to overriding the default behaviors of towncrier by copying those overrides to every downstream project. I accepted the title_format = "{version}" because the skeleton system has a more elegant approach to date generation, but I really want to avoid adding large amounts of boilerplate to override behaviors not caused by this system.

I suggest raising this issue with towncrier to see if they can change their default behavior to reflect best practices. If not, then we'll just have to rely on the somewhat distracting presentation or switch to another tool that has better defaults or wrap towncrier so it has better defaults.

Configuration is a form of tech debt, so I'd like to limit it.

• If we want a minor version bump, then we need to use a .feature.rst file. However this will add changelog lines like "Deprecated feature X" in the Features section. Meanwhile the Deprecations and Removals will not have any deprecations...

This is the best choice given the default behaviors of towncrier.

Also, should doc changes be related to a patch update instead of minor?

I don't feel strongly either way, which means I probably flip-flop between them.

I've typically used minor as the default bump for any change (to the code), and reserved patch for any bugfix against previous changes. For docs (and test-only changes), I'm somewhat inclined to use patch, just because it's not changing anything about the implementation. In fact, I'll often omit the changelog altogether, as it really doesn't affect the behavior, which is the main thing that versioning is about.

[abravalheri]

Thanks Jason, there has been some related discussion in twisted/towncrier#77, and as I understand in the ticket, the resolution comes from using custom configuration.

I have created a new discussion to see if they have an interest in changing the default sections: twisted/towncrier#704.

---

What I was thinking is that we also could do something like the following:

• Create a common configuration file that is shipped inside of a single package and shared among all the projects, this way we can reduce the boilerplate. For example jaraco/develop/_towncrier.toml.
• In jaraco.develop.towncrier.run we could add a CLI option:

  def run(command, *args):
      config = importlib.resources.files("jaraco.develop").joinpath("_towncrier.toml"):
      with importlib.resources.as_file(config) as config_file:
          cmd = (
              sys.executable,
              '-m',
              'towncrier',
              command,
              '--version',
              semver(get_version()),
              '--config',
              config_file,
          ) + args
          subprocess.check_call(cmd)

  However, this does hinder the ability of per-project towncrier.toml (I can see you use it skeleton)

I have explored this possibility in jaraco/jaraco.develop#30.

---

For docs (and test-only changes), I'm somewhat inclined to use patch, just because it's not changing anything about the implementation. In fact, I'll often omit the changelog altogether, as it really doesn't affect the behavior, which is the main thing that versioning is about.

I have created jaraco/jaraco.develop#29 regarding the docs category, so that we align the existing behaviour to this weak preference.

[jaraco]

What I was thinking is that we also could do something like the following:
...
I have explored this possibility in jaraco/jaraco.develop#30.

Neat idea. Maybe we should adopt that instead of the boilerplate here in skeleton (which now has two settings). I quite like the idea of moving default behaviors into code and out of config.

The real trick is - how to support downstream customizations (when the downstream projects have legitimate reasons to customize the behavior) and especially conflicts/overrides. Ideally, there'd be a way for the projects to extend and override the defaults (from both towncrier and jaraco.develop).