devguide
devguide copied to clipboard
python
Clarify where docs fixes can be backported
The status key for branches has lists of changes that can go in, and the lists look exclusive:
feature:
- new features, bugfixes, and security fixes are accepted.
prerelease:
- feature fixes, bugfixes, and security fixes are accepted for the upcoming feature release.
bugfix:
- bugfixes and security fixes are accepted, new binaries are still released. (Also called maintenance mode or stable release)
security:
- only security fixes are accepted and no more binaries are released, but new source-only versions can be released
end-of-life:
- release cycle is frozen; no further changes can be pushed to it.
This makes it a bit awkward to backport docs changes, especially now that the lists are included in the tag descriptions.
AFAIK, docs fixes don't need RM approval in feature, prerelease and bugfix branches. (Security branches are locked so any change needs the RM in the loop.) Is that right, @pablogsal @Yhg1s ?
I'm not sure where it's formally written down specifically, but AFAIK the de-facto policy has been that docs changes that don't touch the code are always backported to bugfix branches so long as they aren't inapplicable to the branch in question (or would result in tricky merge conflicts that would need to be manually resolved), because:
- They don't touch the code, typically fix defects, and per devguide and repo policy aren't user-impactful enough to require NEWS entries
- This ensures that users benefit from them right away rather than only getting them when also upgrading to a new Python feature version,
- This also avoids continuing bug reports for them due to still being present on the default live docs site
- And perhaps most importantly, backporting consistently avoids creating likely merge conflicts with future backports
By contrast, for security branches, general and RM practice as discussed on Discord has been to only backport docs changes relevant to the security/etc. changes that the RM has approved for that branch, as well as any other security-relevant docs changes (rare, but in a recent example, fixing a maliciously-hijacked URL). Of course, its ultimately up to the RMs what goes in to these branches since everything is manually approved, AFAIK.
AFAIK, nothing above conflicts with this, it just doesn't comment on docs changes specifically. However, it would probably be a good idea to include an explicit note to this effect summarizing this (and maybe a PSA to the core dev team), as it often comes up on PRs and I'm not sure everyone is uniformly aware of and consistently applying the backport labels—it's not that hard for anyone not dealing with multiple docs PRs every day like we are to not remember to add them.
Looks like the detailed general policy should be described in Development cycle, and the status page should be a quick overview of the current state of the branches.
Ah, okay. In that case, we could just reword the first three here to say ... bugfixes, docs changes and security fixes ... and the security one to say only security fixes (and security-related docs fixes) are... and a few sentences or a short paragraph to the Development cycle page under the Maintenance Branches hdaing describing the current docs policy as detailed above. does that work?
@JelleZijlstra has written some notes at https://jellezijlstra.github.io/cpython#backporting
Related: https://github.com/python/devguide/issues/503 asking about backporting in general.
The related https://github.com/python/devguide/pull/1169 has been merged.
For this issue, do we still need some changes?