Skip to content

Clarify version policy #777

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.

Sign up for GitHub

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
AlexWaygood merged 8 commits into from
Jul 8, 2026
+10 −10
Merged

Clarify version policy #777

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
4549145
Clarify version policy
srittau Jul 2, 2026
0dc7b85
Remove the 'Development version' section
srittau Jul 2, 2026
e29b457
More examples and guidance
srittau Jul 2, 2026
fa0a703
Use consistent markup
srittau Jul 2, 2026
7bb48d2
Apply suggestions and link to the existing policy
srittau Jul 3, 2026
8e6ce74
Merge branch 'main' into contrib-versions
srittau Jul 3, 2026
d057821
Also link to the versioning policy in the first section
srittau Jul 3, 2026
55d3b7e
Update CONTRIBUTING.md
srittau Jul 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,11 @@ Starting with version 4.0.0, `typing_extensions` uses
for more detail.

## Development version
After a release the version is increased once in [pyproject.toml](/pyproject.toml) and
appended with a `.dev` suffix, e.g. `4.0.1.dev`.
Further subsequent updates are not planned between releases.

After a release the patch version is increased in [pyproject.toml](/pyproject.toml) and
appended with a `.dev0` suffix, e.g. `4.0.1.dev0`.

When a new feature is added we will increase the minor version once between releases. For example, from 4.0.1.dev0 to 4.1.0.dev0.
Comment thread
srittau marked this conversation as resolved.
Outdated

# Type stubs

Expand Down Expand Up @@ -111,4 +113,4 @@ pipx run pre-commit run -a
- Release automation will finish the release. You'll have to manually
approve the last step before upload.

- After the release has been published on PyPI upgrade the version in number in [pyproject.toml](/pyproject.toml) to a `dev` version of the next planned release. For example, change 4.1.1 to 4.X.X.dev, see also [Development versions](#development-version). # TODO decide on major vs. minor increase.
- After the release has been published on PyPI upgrade the version in number in [pyproject.toml](/pyproject.toml) to a `dev` version of the next planned release. For example, change 4.1.1 to 4.1.2.dev0, see also [Development versions](#development-version).

@AlexWaygood AlexWaygood Jul 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the "next planned release" language here is a bit confusing, no? We never plan to do a patch release; we only make a patch release if there was a bug in the latest minor release. But as your helpful example later on makes clear, we should really bump the version from 4.1.0 -> 4.1.1.dev0 rather than 4.1.0 -> 4.2.0.dev0.

Also, what do we do for rc releases? After 4.17.0rc1 is released, does the version bump to 4.17.0.dev? What if we then make an rc2 release the next day? That might lead us to go from 4.17.0rc1 -> 4.17.0.dev0 -> 4.17.0rc2 -> 4.17.0.dev0 -> 4.17.0... so I guess after rc1 is released, we should actually bump the version to 4.17.0rc2.dev0, even if we don't plan for an rc2 release? Then the sequence would go 4.17.0rc1 -> 4.17.0rc2.dev0 -> 4.17.0rc2 -> 4.17.0rc3.dev0 -> 4.17.0 -> 4.17.0.dev0.

It would be really helpful to have explicit examples for what to do after an rc release, and what to do between rc releases, in my opinion. We always do rc releases these days, so it's pretty relevant to the release process.

@srittau srittau Jul 2, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added some more examples and guidance. This seems fairly complex, but it really isn't. Before a release: Make sure the version number makes sense. After a release: Bump patch and add .dev0.

@JelleZijlstra JelleZijlstra Jul 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So if we just released 4.1.1, when would we go to 4.2dev0 instead of 4.1.2dev0?

@srittau srittau Jul 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we could (should?) bump the version to 4.2.0dev0 when adding the first new feature that would require a minor version bump. (That's how I do it for my projects.)

@srittau srittau Jul 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively we could always bump the minor version after a release and use a separate branch from the last release when we need to do a patch release. (In my opinion the best solution for semver projects with frequent changes, but probably a bit too complicated for typing-extensions).

@AlexWaygood AlexWaygood Jul 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we could (should?) bump the version to 4.2.0dev0 when adding the first new feature that would require a minor version bump. (That's how I do it for my projects.)

I guess that makes sense, but I don't feel excited about having to think every time we land a PR about whether the change is significant enough to warrant bumping the version number

@srittau srittau Jul 3, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In practice, you will recheck that before making the next release anyway, so that's not super-critical.

Loading