DOC: clarify the milestoning and backport policy wording #25652

tacaswell · 2023-04-09T22:26:39Z

make less prescriptive
fix formatting (the milestone guidelines were in a nested list?)
minor wording tweaks

doc/devel/coding_guide.rst

story645 · 2023-04-09T23:54:59Z

doc/devel/coding_guide.rst

+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.


I know you didn't touch this in this PR, but maybe uninverting the sentence will make it clearer? Something like (and I admit document is probably the wrong word here)

Suggested change

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.

Setting a milestone documents which release a PR targets but does not imply or guarantee that the PR will be merged for that release.

Suggestion:

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.

timhoffm · 2023-04-10T07:17:25Z

doc/devel/coding_guide.rst

+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.


Suggestion:

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.

doc/devel/coding_guide.rst

rcomer

Thanks @tacaswell this seems much clearer to me. I just have one point that I’m still not quite clear on. Sorry if I’m being overly pedantic!

rcomer · 2023-04-11T19:37:33Z

doc/devel/coding_guide.rst

+Other changes, such as regressions against older releases or 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.


This bit about advocating for a backport is not something I’ve observed in the admittedly short time I’ve been here. I think we more often state why we’re not backporting something.

QuLogic · 2023-04-15T01:36:20Z

doc/devel/coding_guide.rst


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


Suggested change

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

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

QuLogic · 2023-04-15T01:37:16Z

doc/devel/coding_guide.rst

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


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)

QuLogic · 2023-04-15T01:37:45Z

doc/devel/coding_guide.rst

-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.


Suggested change

and may attempt to backport regressions introduced in older releases.

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

rcomer · 2023-04-17T13:18:34Z

Cycling in hope of picking up #25672…

rcomer · 2023-04-17T13:21:12Z

Cycling in hope of picking up #25672…

Well that didn’t work. @tacaswell would you mind rebasing?

- make less prescriptive - fix formatting (the milestone guidelines were in a nested list?) - minor wording tweaks closes matplotlib#25649 Co-authored-by: Jody Klymak <jklymak@gmail.com> Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

story645

Grammar/wording suggestions, but since there are two reviews already I can make the changes in a follow up PR.

story645 · 2023-04-18T14:37:29Z

doc/devel/coding_guide.rst

- fixes for regressions against the last two releases.
+- critical bug fixes (segfault, failure to import, things that the
+  user can not work around)
+- fixes for regressions introduced in last two minor releases


Suggested change

- fixes for regressions introduced in last two minor releases

- fixes for regressions introduced in the last two minor releases

story645 · 2023-04-18T14:38:19Z

doc/devel/coding_guide.rst

+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


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

story645 · 2023-04-18T14:41:00Z

doc/devel/coding_guide.rst

-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


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

story645 · 2023-04-18T14:45:40Z

doc/devel/coding_guide.rst

+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.


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.

rcomer · 2023-04-18T15:10:51Z

I think merging here and opening a follow-up PR for further wording tweaks is a good plan.

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

tacaswell added this to the v3.8.0 milestone Apr 9, 2023

tacaswell requested a review from rcomer April 9, 2023 22:26

jklymak reviewed Apr 9, 2023

View reviewed changes

doc/devel/coding_guide.rst Outdated Show resolved Hide resolved

story645 reviewed Apr 9, 2023

View reviewed changes

timhoffm reviewed Apr 10, 2023

View reviewed changes

rcomer reviewed Apr 11, 2023

View reviewed changes

github-actions bot added the status: needs rebase label Apr 12, 2023

tacaswell force-pushed the doc/backports branch from c7f44a6 to e89213e Compare April 13, 2023 14:59

github-actions bot removed the status: needs rebase label Apr 13, 2023

tacaswell requested a review from rcomer April 14, 2023 20:00

QuLogic approved these changes Apr 15, 2023

View reviewed changes

rcomer closed this Apr 17, 2023

rcomer reopened this Apr 17, 2023

tacaswell force-pushed the doc/backports branch from e89213e to fedddea Compare April 17, 2023 22:28

rcomer approved these changes Apr 18, 2023

View reviewed changes

story645 reviewed Apr 18, 2023

View reviewed changes

rcomer merged commit fb64929 into matplotlib:main Apr 18, 2023

tacaswell deleted the doc/backports branch April 18, 2023 20:18

story645 added a commit to story645/matplotlib that referenced this pull request Apr 21, 2023

grammar/wording tweak follow up to matplotlib#25652

5201e11

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

story645 mentioned this pull request Apr 21, 2023

grammar/wording tweak for backports #25739

Merged

eslothower pushed a commit to eslothower/matplotlib that referenced this pull request May 3, 2023

grammar/wording tweak follow up to matplotlib#25652

ca17800

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

		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.

	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.
	Setting a milestone documents which release a PR targets but does not imply or guarantee that the PR will be merged for that release.

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

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

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

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

	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

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

Uh oh!

DOC: clarify the milestoning and backport policy wording #25652

DOC: clarify the milestoning and backport policy wording #25652

Uh oh!

Conversation

tacaswell commented Apr 9, 2023

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rcomer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rcomer commented Apr 17, 2023

Uh oh!

rcomer commented Apr 17, 2023

Uh oh!

story645 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rcomer commented Apr 18, 2023

Uh oh!

Uh oh!

story645 left a comment •

edited

Loading