Skip to content

DOC: clarify the milestoning and backport policy wording #25652

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 18, 2023
Merged

DOC: clarify the milestoning and backport policy wording #25652

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 36 additions & 25 deletions doc/devel/coding_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,25 +273,28 @@ Labels
Milestones
----------

* Set the milestone according to these rules:
Set the milestone according to these guidelines:

* *New features and API changes* are milestoned for the next minor release
``v3.N.0``.
* *New features and API changes* are milestoned for the next minor release
``v3.N.0``.

* *Bugfixes, tests for released code, and docstring changes* are milestoned
for the next patch release ``v3.N.M``.
* *Bugfixes, tests for released code, and docstring changes* may be milestoned
for the next patch release ``v3.N.M``.

* *Documentation changes* (all .rst files and examples) are milestoned
``v3.N-doc``.
* *Documentation changes* (all .rst files and examples) may be milestoned
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* *Documentation changes* (all .rst files and examples) may be milestoned
* *Documentation changes* (only .rst files and examples) may be milestoned

``v3.N-doc``.

If multiple rules apply, choose the first matching from the above list.
If multiple rules apply, choose the first matching from the above list. See
:ref:`backport-strategy` for detailed guidance on what should or should not be
backported.

Setting a milestone does not imply or guarantee that a PR will be merged for that
release, but if it were to be merged what release it would be in.
The milestone marks the release a PR should go into. It is an intent but can
be changed because of re-evaluation of the PR scope and maturity or release
planning.
Comment on lines +291 to +293
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The milestone marks the release a PR should go into. It is an intent but can
be changed because of re-evaluation of the PR scope and maturity or release
planning.
The milestone marks the release a PR should go into. It states intent, but can
be changed because of release planning or re-evaluation of the PR scope and maturity.


All of these PRs should target the main branch. The milestone tag triggers
an :ref:`automatic backport <automated-backports>` for milestones which have
a corresponding branch.
All Pull Requests should target the main branch. The milestone tag triggers
an :ref:`automatic backport <automated-backports>` for milestones which have
a corresponding branch.

.. _pr-merging:

Expand Down Expand Up @@ -440,26 +443,34 @@ Other branches are fed through :ref:`automatic <automated-backports>` or
targeting other branches is only rarely necessary for special maintenance
work.

.. backport_strategy:
.. _backport-strategy:

Backport strategy
-----------------

We will always backport to the patch release branch (*v3.N.x*):
Backports to the patch release branch (*v3.N.x*) are the changes that will be
included in the next patch (aka bug-fix) release. The goal of the patch
releases is to fix bugs without adding any new regressions or behavior changes.
We will always attempt to backport:

- critical bug fixes (segfault, failure to import, things that the user cannot
work around)
- fixes for regressions against the last two releases.
- critical bug fixes (segfault, failure to import, things that the
user can not work around)
Comment on lines +456 to +457
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- critical bug fixes (segfault, failure to import, things that the
user can not work around)
- critical bug fixes (segfault, failure to import, things that the
user cannot work around)

- fixes for regressions introduced in last two minor releases
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- fixes for regressions introduced in last two minor releases
- fixes for regressions introduced in the last two minor releases


Everything else (regressions against older releases, bugs/api
inconsistencies the user can work around in their code) are on a
case-by-case basis, should be low-risk, and need someone to advocate
for and shepherd through the backport.
and may attempt to backport regressions introduced in older releases.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
and may attempt to backport regressions introduced in older releases.
and may attempt to backport fixes for regressions introduced in older releases.


In the case where the backport is not clean, for example if the bug fix is
built on top of other code changes we do not want to backport, balance the
effort and risk of re-implementing the bug fix vs the severity of the bug.
When in doubt, err on the side of not backporting.

When backporting a Pull Request fails or is declined re-milestone the original
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When backporting a Pull Request fails or is declined re-milestone the original
When backporting a Pull Request fails or is declined, re-milestone the original

PR to the next minor release and leave a comment explaining why.

The only changes to be backported to the documentation branch (*v3.N.M-doc*)
are changes to :file:`doc`, :file:`examples`, or :file:`tutorials`.
Any changes to :file:`lib` or :file:`src` including docstring-only changes
should not be backported to this branch.
are changes to :file:`doc`, :file:`examples`, or :file:`tutorials`. Any
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
are changes to :file:`doc`, :file:`examples`, or :file:`tutorials`. Any
are changes to :file:`doc`, :file:`examples`, :file:`tutorials` or :file:`galleries` Any

changes to :file:`lib` or :file:`src`, including docstring-only changes, must
not be backported to this branch.


.. _automated-backports:
Expand Down