Update the documented release process #2277

sirosen · 2025-11-18T19:49:04Z

These updates are to "match reality". I considered leaving some of the surrounding text (e.g., "Do not hesitate to ask questions...") alone, but judged that our current maintenance culture makes such text unnecessary.

This PR should resolve this comment.

I decided not to add a contrib changelog note for this one. In this particular case it's purely doc and only relevant to the maintainers who do releases.

Contributor checklist

~~Included tests for the changes.~~
A change note is created in changelog.d/ (see changelog.d/README.md for instructions) or the PR text says "no changelog needed".

Maintainer checklist

If no changelog is needed, apply the bot:chronographer:skip label.
~~Assign the PR to an existing or new milestone for the target version (following Semantic Versioning).~~

These updates are to "match reality". I considered leaving some of the surrounding text (e.g., "Do not hesitate to ask questions...") alone, but judged that our current maintenance culture makes such text unnecessary.

CONTRIBUTING.md

webknjaz · 2025-11-18T21:35:10Z

CONTRIBUTING.md

-
-Do not hesitate to ask questions if you have any before performing a release.
+- Pull the latest changes to `main` locally.
+- Create an unsigned tag with the release version number prefixed with a `v`, _e.g., `git tag v3.4.0`_, and push.


Better make it annotated

Suggested change

- Create an unsigned tag with the release version number prefixed with a `v`, _e.g., `git tag v3.4.0`_, and push.

- Create an unsigned tag with the release version number prefixed with a `v`, _e.g., `git tag -a v3.4.0`_, and push it to the upstream repository.

To make it an annotated tag we need a message. So... git tag -a v3.4.0 -m 'v3.4.0'?

Ah, right. Yes.
Also, might be a good idea to have an explicit reference git tag -a v3.4.0 -m v3.4.0 upstream/main (post git fetch upstream or git fetch --all).

Just remembered how we tried to include Git instructions in attrs (python-attrs/attrs#1105 / python-attrs/attrs#1123). But that ended up being removed (python-attrs/attrs@52dfaf0).

So maybe this is overkill.

I think it's a balance we need to strike. Unless we're actually trying to script it out into a runbook of some kind, we should leave some gaps to let the process fit the release engineer's environment.

For now, I've written it out as git tag -a v3.4.0 -m v3.4.0, and I think that's good -- adapting that command as needed and pushing that tag is left to the release engineer's discretion. I also like that we're showing steps with a specific (bogus) release version, rather than git tag -a "v$VERSION" -m "v$VERSION" or stuff like that.

Yeah, that's fair. I hope that #2274 will eventually bring us closer to a single-button process.

CONTRIBUTING.md

webknjaz · 2025-11-18T21:43:32Z

CONTRIBUTING.md

+- Create an unsigned tag with the release version number prefixed with a `v`, _e.g., `git tag v3.4.0`_, and push.
+- Create a GitHub Release, populated with a copy of the changelog. Some of the markdown will need to be reformatted into GFM.
+  The release title and tag should be the newly created tag.
+- A GitHub Workflow will trigger off of the release to publish to PyPI. A member of `pip-tools-leads` must approve the publication step.


Maybe link the workflow runs page and the team?

Suggested change

- A GitHub Workflow will trigger off of the release to publish to PyPI. A member of `pip-tools-leads` must approve the publication step.

- A [GitHub Workflow] will trigger off of the release to publish to PyPI. A member of [`pip-tools-leads` team] must approve the publication step.

I'm happy to link the workflow runs page. Is the team publicly visible? Or visible to everyone in the org?
(It's not viewable unauthenticated, and I don't have a second github account handy to check on this)

I think teams are visible to all GH org members.

webknjaz · 2025-11-18T21:45:01Z

CONTRIBUTING.md

-Please be mindful of other before and when performing a release, and use this access responsibly.
-
-Do not hesitate to ask questions if you have any before performing a release.
+- Pull the latest changes to `main` locally.


Technically, this does require pulling but just fetching.

True. IMO, the workflow which is likely to be familiar to people is git checkout main; git pull.

How about "Fetch the latest changes to main locally."? Since there's no command given in the doc, I think that leaves me free to checkout+pull (which is what I typically do).

FWIW, kids these days would do git switch. Also, pulling includes merge, which might create a merge commit. At least add --ff.

I have pull.ff = only in my git config! 😁

I should probably start trying git switch though.

In any case, I updated to the Fetch the latest changes wording. LMK if you feel like it's good this way or should be further refined.

I have pull.ff = only in my git config! 😁

Me too!

I should probably start trying git switch though.

I've been trying to start but it's difficult to change habits. omz gives me aliases and I'm so used to gco / gcb. And now I'm trying to remember that it's gsw / gswc..

The wording seems good.

webknjaz · 2025-11-18T21:47:07Z

CONTRIBUTING.md

- Update the [CHANGELOG] with the version, date and add the text from [drafter release](https://github.com/jazzband/pip-tools/releases).
+- Create a branch for the release. _e.g., `release-3.4.0`_.
+- Use `towncrier` to update the [CHANGELOG], _e.g., `towncrier build --version v3.4.0`_.
 - Push the branch to your fork and create a pull request.


Since this is talking about both upstream and fork. It's probably worth defining the assumed git remote names at the beginning of the document. Might be origin and fork, or upstream and origin.

I prefer upstream+origin mildly -- it's what I use, and I'm one of the primary consumers of this doc. I'll add a line for it.

We have upstream + origin in ansible/ansible, I think. But I tend to use fork. Still, I know how to adapt so it doesn't matter.

webknjaz · 2025-11-18T21:50:09Z

CONTRIBUTING.md


-Jazzband aims to give full access to all members, including performing releases, as described in the
-[Jazzband Releases documentation](https://jazzband.co/about/releases).
+Releases require approval by a member of the `pip-tools-leads` team.


Suggested change

Releases require approval by a member of the `pip-tools-leads` team.

Releases require approval by a member of the [`pip-tools-leads` team].

webknjaz

Can we link the release workflow specifically?

sirosen · 2025-11-18T22:57:25Z

Sure! I wasn't sure whether or not we wanted to be that specific about it. New revision with that + the team link coming momentarily.

CONTRIBUTING.md

webknjaz · 2025-11-19T00:31:43Z

CONTRIBUTING.md

+- Create a GitHub Release, populated with a copy of the changelog.
+  Some of the markdown will need to be reformatted into GFM.
+  The release title and tag should be the newly created tag.


Now that we have the Announcements category in Discussions, the GH Release creation should always create a discussion — there's a checkbox for it with a drop-down for the category. This must be done at the time of the initial GH Release creation — once created, it's impossible to link a discussion to an existing release entry.

For right now I'll just add a text note about this, but this also motivates me to do a second pass over this doc and introduce gh CLI commands in the future.

Having a command handy for gh release create --discussion-category Announcements ... would probably prevent mistakes.

Yep. In fact, I was looking at the pytest release automation (actually fixing something when publishing v9.0.1 broke), I realized that it can now be triggered by gh commands. And I realized that it's possible to have GH CLI extensions that are invocable as subcommands. It might be interesting to explore a gh release-pip-tools one day. Not sure yet.

CONTRIBUTING.md

Also, avoid very long lines by inserting more semantic breaks into the new release documentation. Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>

sirosen · 2025-11-20T17:01:35Z

I did a rebase to squash together all of the recent changes, just to clarify in case the diff looks odd at all.

Update the documented release process

ed995a6

These updates are to "match reality". I considered leaving some of the surrounding text (e.g., "Do not hesitate to ask questions...") alone, but judged that our current maintenance culture makes such text unnecessary.

sirosen requested a review from webknjaz November 18, 2025 19:49

sirosen added the bot:chronographer:skip label Nov 18, 2025

webknjaz reviewed Nov 18, 2025

View reviewed changes

sirosen force-pushed the update-release-doc branch 2 times, most recently from 15154fc to 524edd3 Compare November 18, 2025 22:17

webknjaz reviewed Nov 18, 2025

View reviewed changes

webknjaz reviewed Nov 19, 2025

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

webknjaz reviewed Nov 19, 2025

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

Apply suggestions from code review

62ab395

Also, avoid very long lines by inserting more semantic breaks into the new release documentation. Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>

sirosen force-pushed the update-release-doc branch from 5fb37bd to 62ab395 Compare November 20, 2025 17:00

webknjaz approved these changes Nov 20, 2025

View reviewed changes

webknjaz added this pull request to the merge queue Nov 20, 2025

Merged via the queue into jazzband:main with commit edd379a Nov 20, 2025
52 checks passed

sirosen deleted the update-release-doc branch November 20, 2025 21:58

	- Create an unsigned tag with the release version number prefixed with a `v`, _e.g., `git tag v3.4.0`_, and push.
	- Create an unsigned tag with the release version number prefixed with a `v`, _e.g., `git tag -a v3.4.0`_, and push it to the upstream repository.

	- A GitHub Workflow will trigger off of the release to publish to PyPI. A member of `pip-tools-leads` must approve the publication step.
	- A [GitHub Workflow] will trigger off of the release to publish to PyPI. A member of [`pip-tools-leads` team] must approve the publication step.

	Releases require approval by a member of the `pip-tools-leads` team.
	Releases require approval by a member of the [`pip-tools-leads` team].

Uh oh!

Update the documented release process #2277

Update the documented release process #2277

Uh oh!

Conversation

sirosen commented Nov 18, 2025 • edited by webknjaz Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contributor checklist

Maintainer checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

webknjaz left a comment

Choose a reason for hiding this comment

Uh oh!

sirosen commented Nov 18, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sirosen commented Nov 20, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sirosen commented Nov 18, 2025 •

edited by webknjaz

Loading