Skip to content

Towncrier: move process section to the end #12539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 3, 2024

Conversation

sbidoul
Copy link
Member

@sbidoul sbidoul commented Feb 24, 2024

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.

@sbidoul sbidoul added the skip news Does not need a NEWS file entry (eg: trivial changes) label Feb 24, 2024
@sbidoul sbidoul added this to the 24.1 milestone Feb 24, 2024
@pradyunsg
Copy link
Member

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.

@pradyunsg
Copy link
Member

(it's a non-blocking concern though, mostly just me thinking aloud about what else might make sense to do)

@webknjaz
Copy link
Member

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.

@webknjaz
Copy link
Member

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.

@pradyunsg pradyunsg merged commit ae5fff3 into pypa:main Mar 3, 2024
@pradyunsg
Copy link
Member

Changing it into specific focused and well-documented categories

I think that works well -- let's do this in a follow up! :)

@sbidoul sbidoul deleted the tweak-towncrier-sbi branch March 10, 2024 10:15
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 26, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
skip news Does not need a NEWS file entry (eg: trivial changes)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants