Explain that the contributors should base changes against main
#983
Conversation
This isn't a particularly common issue but every now and then somebody will waste their time by preparing a change against a maintenance branch instead of working with `main` from the get-go. This change serves as a reminder to contributors to think about the `main` branch first.
| * NOTE: Don't work on old branches of Python. Even if you're working on | ||
| a fix for a bug you discovered in an older version of Python, we | ||
| want to fix it in ``main`` first and then | ||
| :ref:`port your fix back <branch-merge>` later. |
There was a problem hiding this comment.
Instead of adding this note I would add a link to the paragraph below.
There was a problem hiding this comment.
And if it is a note and is called out with an ad-hoc NOTE: plain text, we should just make it an actual ``.. note::`.
| First, make your change against the right version of Python. Even if you're | ||
| fixing a bug, your fix needs to go to the ``main`` branch first. After the | ||
| fix is merged, it will be :ref:`ported back <branch-merge>` to older | ||
| maintenance releases as well. That way we ensure all affected versions are | ||
| handled. Unless you're sure that your change does not apply to ``main``, | ||
| don't base your fixes on old versions of Python. |
There was a problem hiding this comment.
The tone seems to assume that they are going to do it against the wrong version. I would use a more neutral tone and state that almost all changes (including bug and security fixes) should be done against main, but in certain cases they should be done on older branches (maybe list a couple of examples (IIRC they are already mentioned somewhere)).
Providing the background for this (e.g. by explaining that we backport fixes like you did) and cases where the PR should be done on old branches, will help reassure the reader about which versions will receive the fix.
| handled. Unless you're sure that your change does not apply to ``main``, | ||
| don't base your fixes on old versions of Python. | ||
|
|
||
| Second, make sure to follow Python's style guidelines. For Python code you |
There was a problem hiding this comment.
Sidenote: To avoid noisy, tedious and easy to mess up manual renumbering like this, a long list of prose-numbered paragraphs, and where there isn't an inherent order, it would be better to reformat this as an unordered (bulleted) list instead (or at least use an auto-numbered ordered list). But perhaps out of scope here.
There was a problem hiding this comment.
I remember we already deferred doing this once to a separate PR so I'll just do it here then.
|
Thanks for your insightful comments. Addressed in the update. Current state:
|
This isn't a particularly common issue but every now and then somebody will waste their time by preparing a change against a maintenance branch instead of working with
mainfrom the get-go.This change serves as a reminder to contributors to think about the
mainbranch first.Key changes:
