Skip to content

Added more pre-release documentation and email template to RELEASING.md - #1255

Closed
m1yag1 wants to merge 1 commit into
mainfrom
update-releasing-docs
Closed

Added more pre-release documentation and email template to RELEASING.md#1255
m1yag1 wants to merge 1 commit into
mainfrom
update-releasing-docs

Conversation

@m1yag1

@m1yag1 m1yag1 commented Jul 10, 2025

Copy link
Copy Markdown
Contributor

While the two processes are very similar, when I had to go through the pre-release steps it was easier to have them written out in detail. Additionally, I felt having an email template was a nice thing to have.


📚 Documentation preview 📚: https://globus-sdk-python--1255.org.readthedocs.build/en/1255/

@m1yag1 m1yag1 added the no-news-is-good-news This change does not require a news file label Jul 10, 2025
@sirosen

sirosen commented Jul 11, 2025

Copy link
Copy Markdown
Member

I really don't want the document to be so long. When I'm running a release of a project, I typically cat RELEASING.{md,adoc,rst} in order to see the steps, and making the document too long makes it very hard to navigate as undecorated text. Being able to drive development, testing, and releasing all from the terminal is, I think, a reasonable goal for our projects.

We're already being really verbose and prescriptive here in a way that I think is "a bit much". For contrast, here's the entirety of RELEASING.md for one of the projects I solo maintain:

# Releasing

- Bump the version with `./scripts/bump-version.py NEW_VERSION`
- Add, commit with `git commit -m 'Bump version for release'`, and push
- Create a release tag, which will auto-publish to testpypi (`make release`)
- Create a GitHub release, which will auto-publish to pypi (web UI)

I'll accept that might be too short for a shared project with more maintainers (and we actually have more mechanical steps to list, like the PR process), but doubling the length of a document which already takes a full page-length to cat is, for me, crossing a barrier in the other direction.

My ideal version of our releasing doc for the SDK would be something like...

# Releasing

## Prereqs

- Git configured with a GPG key for signing
- GitHub CLI (`gh`)

## Procedure

- Update the version and create a release branch with `./scripts/release.sh start NEW_VERSION`
- Update changelog with `./scripts/release.sh prepare`
- Add and commit changes; `git commit -m 'Bump version and changelog for release'`
- Create the release PR with `./scripts/release.sh pr`
- After approval, merge the PR and update `main` with `git checkout main; git pull`
- Tag the release, which will publish to test-pypi, with `./scripts/release.sh tag`
- Create a GitHub release, which will publish to pypi, with `./scripts/release.sh github`

This obviously assumes that we setup a script with the relevant functionality, but given that it's 90% written already, that shouldn't be that hard.


I doubt we have full alignment from all current maintainers on exactly what we want this to look like, and I may be an outlier in wanting to be able to cat the file and have a nice experience. However, I do think my preference is worth something, and a procedural doc should be very short and to the point.

If we're going to document a prerelease process as distinct from the normal release process (do we really need to?), I would like it to at least be a separate doc.
But really, I would like us to be trending in the opposite direction. If we want alphas to be marked as prereleases in GitHub Releases (we do) and we don't feel we can trust engineers to do that (fair enough), I think the right thing to do is to script wrapping the release creation step such that we automatically pass --prerelease to the gh CLI when we create the release. That way, we codify that knowledge in the repo but without making our developer docs harder to work with -- ideally, they become easier.

@m1yag1 m1yag1 closed this Jul 11, 2025
@m1yag1
m1yag1 deleted the update-releasing-docs branch July 11, 2025 15:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-news-is-good-news This change does not require a news file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants