pip
pip copied to clipboard
pypa
Towncrier: move process section to the end
When doing the releases was surprised to see the process subsection at the beginning of NEWS sections.
My reasoning is that it matters less than the others to end users, so I propose to move it to the end.
Hmm... looking back at our actual usage of the changelog, it might make sense to drop this section entirely and split the deprecations and removals into separate categories.
I don't think changes to pip's development processes are typically useful to call out in the changelog and the only thing that has been used for thus far is deprecation callouts, presumably since the removal doesn't seem to fit for something being merely deprecated / migrated.
(it's a non-blocking concern though, mostly just me thinking aloud about what else might make sense to do)
I was recently improving the changelog structure in the @aio-libs projects, looking into what pip does, among others. I ended up putting a similar section towards the end but re-framing it as several more granular sections like contributor-facing and downstream/packaging-friendly. See https://yarl.aio-libs.org/en/latest/changes/ + https://github.com/aio-libs/yarl/blob/bd5ff24/towncrier.toml#L18-L68. I documented their purpose like so https://yarl.aio-libs.org/en/latest/contributing/guidelines/#alright-so-how-to-add-a-news-fragment.
I thought, you'll find this example useful, perhaps.
Hmm... looking back at our actual usage of the changelog, it might make sense to drop this section entirely and split the deprecations and removals into separate categories.
I also looked into a few recent releases @ https://pip.pypa.io/en/latest/news/ with Ctrl+F for "Process". The draft section has news about contributor and downstream-facing changes in this category. The 24.0 one is downstream/packaging; 23.3 is contrib; 23.2 is a feature deprecation (?); 22.2 is more of a bugfix (or forward compat / feature).
So I think that it is indeed misused, however this is probably a consequence of the category being generic and its purpose being seemingly underdefined. Changing it into specific focused and well-documented categories, like I did elsewhere, might be the thing that could improve clarity going forward. Building a shared understanding of what's the purpose of the fragment types is useful regardless of removal.
I understand where the proposal to get rid of it is coming from but it seems to me that making it clearer by splitting would be more useful to the changelog consumers compared to sticking these entries into categories that might be even less related.
Changing it into specific focused and well-documented categories
I think that works well -- let's do this in a follow up! :)