Repository navigation
Communicating our versioning policy better #10837
Description
#10825 made it clear that we need to communicate our versioning policy better. The first step is to add a note about it to package descriptions as suggested by me in typeshed-internal/stub_uploader#104. But I think we could also communicate the "specialness" of the typeshed part of the version number better. A few ideas:
- Don't reset the version number when the upstream version changes.
- Start with a high number, e.g. 1000 to make it stand out, e.g. 1.2.3.1023
- Use the current date (and limit to one upload per day): 1.2.3.231005
- Bump the version significantly on major changes, e.g. 1.2.3.1023 -> 1.2.3.2000
- Edit: Use epochs, e.g. 45!1.2.3
Personally, I think options 1 and 2 combined would be a good solution, although I find option 3 strangely appealing as well.
Activity
srittau commentedon Oct 12, 2023
I'd like to bump this again. I still think we should at least bump the minimum stub version up to 1000 to signify that it's "special", although I really like the idea to use the current date. A version like 1.2.3.231012 looks weird, but it really stands out. Any opinions?
Akuli commentedon Oct 12, 2023
I like the date versioning (aka calver) idea, and I think it would be a good fit for typeshed.
Maybe we should use full years in the version number, as in
1.2.3.20231012? The meaning is more obvious, and I don't really see any downsides in this.AlexWaygood commentedon Oct 12, 2023
Thanks for bumping @srittau! Agree that our current policy looks too much like we're just making a "micro version bump", which isn't really how we do things here.
I basically agree with @Akuli -- I also quite like the date versioning idea!
srittau commentedon Oct 12, 2023
We also don't need to limit the uploads. Just use the next free date if the current date is already in use. I don't think it's a problem if a package is a day in the future from time to time.
Akuli commentedon Oct 12, 2023
IMO it would be better to limit the uploads. Suppose a contributor is doing large manual changes into a specific package, and makes 5 pull requests with 3 hours between each PR (total time spent would be 12 hours, so not unreasonable). If we merge the PRs quickly, this would get stub-uploader 4 days ahead in one day.
AlexWaygood commentedon Oct 12, 2023
I agree with @Akuli. I also think limiting uploads of any one stubs package to once per day is fine. That's already a much more frequent release schedule than you'll get with basically any other open-source package.
Upload only once per day
Upload only once per day (#106)
Switch stub versioning to calver
srittau commentedon Nov 21, 2023
typeshed-internal/stub_uploader#114
srittau commentedon Dec 20, 2023
And it worked (ignoring the integration test failures): https://pypi.org/project/types-networkx/3.1.0.20231220/