Add warning about reference interop for build numbers

[sethmlarson]

Follow-up from discussion here: https://discuss.python.org/t/guidance-on-wheel-build-numbers-for-external-reference-security-fixes/29621

[webknjaz]

Thanks for the PR! It might be important to clarify cases where it makes sense to use build numbers, I think. For example, a wheel can be published early in the upcoming CPython release cycle but as things evolve and it enters beta/rc, it would probably be reasonable to rebuild a wheel under a newer runtime with zero changes to the source or its deps.

As for the security releases I agree that it's a good idea to bump the patch version number. But also, I'd rebuild the older wheels with a new build number in some cases, when it's possible, in addition to making the new release. This way, I feel like the security fix might reach a wider number of users incidentally. Though, in the announcements, I'd still refer to the new release to reduce possible confusion.

WDYT?

[sethmlarson]

It might be important to clarify cases where it makes sense to use build numbers, I think. For example, a wheel can be published early in the upcoming CPython release cycle but as things evolve and it enters beta/rc, it would probably be reasonable to rebuild a wheel under a newer runtime with zero changes to the source or its deps.

Seems like a good idea to me, I can capture this in this PR!

As for the security releases I agree that it's a good idea to bump the patch version number. But also, I'd rebuild the older wheels with a new build number in some cases, when it's possible, in addition to making the new release. This way, I feel like the security fix might reach a wider number of users incidentally. Though, in the announcements, I'd still refer to the new release to reduce possible confusion.

I'm not sure about "backporting" a fix to an existing release using build numbers, has a few downsides:

• Users seeing that fix being added in a previous version might be confused or think the advisory is incorrect/off-by-one. May incorrectly think they aren't vulnerable.
• Downstream distributors may be confused about which patch/diff contains the fix.
• Users that are consuming the library in apps correctly (ie lockfiles w/ hashes) don't receive the fix.
• Unclear to me how this could work with a deployment pipeline, presumably you'd need to do this manually and potentially not committed to VCS?

In general I don't think we should recommend folks use build numbers this way, there might be some projects where this works for though?

[sethmlarson]

@webknjaz I've updated with a quick blurb about a valid use-case, let me know if the phrasing makes sense or needs tweaking.

[webknjaz]

Thanks! Love it! Sorry for the delay...

[sethmlarson]

Thanks @webknjaz, no worries on the timing! :)