Communicating our versioning policy better

[srittau]

#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.

[srittau]

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]

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]

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]

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]

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]

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.

[srittau]

typeshed-internal/stub_uploader#114

[srittau]

And it worked (ignoring the integration test failures): https://pypi.org/project/types-networkx/3.1.0.20231220/