Repository navigation
run_release should remind the release manager to start rebuild of security-only branches full docs on docs server #433
Description
Activity
Good idea, and easy to implement.
But before we do, here's another idea: re-auto-build security docs?
We've tamed the docs build server considerably in recent years, so we're not building all the docs in a big single sequential loop -- we have one 5-min cron for English HTML, daily for HTML for all languages, and 3-4 times a month for the rest (or something like this), so we get the HTML updated sooner.
So there's likely a much lower cost to re-adding them.
And security branches by definition have much fewer changes. Over the past 12 months:
branch Doc/+NEWScommitsdays with changes main 3019 363 3.15 218 44 3.14 1731 346 3.13 1271 325 3.12 (security) 76 29 3.11 (security) 73 36 3.10 (security) 71 31 So perhaps a daily cron for security would be worthwhile?
We'd need to decide whether to include non-HTML and translations -- any changes to translations would also trigger a build, but I think most translations target newer branches only?
But before we do, here's another idea: re-auto-build security docs?
That would be a better option, sure.
So perhaps a daily cron for security would be worthwhile?
A daily cron for the English HTML shouldn't add much overhead. If the full build with translations could be done infrequently (once a month or, when a doc change is committed, perhaps once a day or week), even better. It's just a question of how much effort someone is willing to put into it. (I'd expect that the larger downstream distributors will supply their own updated documentation packages when they make Python updates available.)
A daily cron for the English HTML shouldn't add much overhead.
Yep, we could do:
- Nothing extra into the 5-minute English HTML cron, so that stays fast.
- The English + translations HTML as part of the daily cron.
- The English + translations non-HTML in the 3-4 times/month cron.
If the full build with translations could be done infrequently (once a month or, when a doc change is committed, perhaps once a day or week), even better.
The build only happens if there have been changes since the last time (doc change, or relevant translation change), so that already prevents plenty of unnecessary rebuilds.
We can keep an eye on the build times, and adjust if necessary.
It's just a question of how much effort someone is willing to put into it.
🙋
I think it's worth it: once set up, it's automated, and less effort than doing manual builds after each security release.
Here's some PRs:
Reacted by Seth Larson
As noted here, a rebuild of the full set of docs for security-only branches is not run automatically on the docs build server as is done for bugfix and feature branches. This was done to substantially reduce the CPU load on the docs build server since the security-only branches do not receive many doc updates and releases are as needed.
Because of this, there should be a RM reminder added to
run_release.pyto ensure that the docs build update has been or will be manually started for security branch releases. (That step should be added to PEP 101 as well if it isn't there already - I didn't see it.)