DOCS: add action items to PR template #18341

brunobeltran · 2020-08-24T19:05:27Z

PR Summary

Adds action items to each checkbox of the PR template.

Per the discussion in #17153, we should be putting any improvements for the developer documentation in to the dev docs themselves, not in the PR template. However, I pulled out a non-controversial (I think) quality of life improvement for new devs into this separate PR, since I still think this bit should be merged.

PR Checklist

[N/A] Has Pytest style unit tests
[N/A] Code is Flake 8 compliant
[N/A] New features are documented, with examples if plot related
[N/A] Documentation is sphinx and numpydoc compliant
[N/A] Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
[N/A] Documented in doc/api/next_api_changes/* if API changed in a backward-incompatible way

brunobeltran · 2020-08-24T19:18:39Z

PR Summary

This is what my proposed new PR template looks like. Compare with the above!

PR Checklist

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (run flake8 on changed files to check).
New features are documented, with examples if plot related.
Documentation is sphinx and numpydoc compliant (the docs should build without error).
Conforms to Matplotlib style conventions (install flake8-docstrings and pydocstyle<4 and run flake8 --docstring-convention=all).
New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

jklymak · 2020-08-24T20:43:50Z

.github/PULL_REQUEST_TEMPLATE.md

+<!-- Please mark any checkboxes that do not apply to this PR as [N/A]. -->
+
+- [ ] Has pytest style unit tests (and `pytest` passes).
+- [ ] Is [Flake 8](https://flake8.pycqa.org/en/latest/) compliant (run `flake8` on changed files to check).
+- [ ] New features are documented, with examples if plot related.
+- [ ] Documentation is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error).
+- [ ] Conforms to Matplotlib style conventions (install `flake8-docstrings` and `pydocstyle<4` and run `flake8 --docstring-convention=all`).
+- [ ] New features have an entry in `doc/users/next_whats_new/` (follow instructions in README.rst there).
+- [ ] API changes documented in `doc/api/next_api_changes/` (follow instructions in README.rst there).


Does it make sense to organize these a bit? Also, I've never run flake8 --docstring-convention=all in my life. Is this really a requirement?

Suggested change



- [ ] Has pytest style unit tests (and `pytest` passes).

- [ ] Is [Flake 8](https://flake8.pycqa.org/en/latest/) compliant (run `flake8` on changed files to check).

- [ ] New features are documented, with examples if plot related.

- [ ] Documentation is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error).

- [ ] Conforms to Matplotlib style conventions (install `flake8-docstrings` and `pydocstyle<4` and run `flake8 --docstring-convention=all`).

- [ ] New features have an entry in `doc/users/next_whats_new/` (follow instructions in README.rst there).

- [ ] API changes documented in `doc/api/next_api_changes/` (follow instructions in README.rst there).



- [ ] Has pytest style unit tests (and `pytest` passes).

- [ ] Is [Flake 8](https://flake8.pycqa.org/en/latest/) compliant (run `flake8` on changed files to check).

- [ ] New features are documented, with examples if plot related.

- [ ] New features have an entry in `doc/users/next_whats_new/` (follow instructions in README.rst there).

- [ ] API changes documented in `doc/api/next_api_changes/` (follow instructions in README.rst there).

- [ ] Documentation is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error).

- [ ] Conforms to Matplotlib style conventions (install `flake8-docstrings` and `pydocstyle<4` and run `flake8 --docstring-convention=all`).

Does it make sense to organize these a bit?

~~I accepted your reorg because it doesn't change anything that anyone would object to, but any further reorg should go into a new PR (feature creep is why #17153 died).~~ Github renders the version you requested really strangely (see below). If you really want, I can reorder the entries, but I think it would make sense to split reorg into a separate PR.

Also, I've never run flake8 --docstring-convention=all in my life. Is this really a requirement?

For the first two weeks or so of me submitting PRs, the majority of comments on my PRs were from @timhoffm, correcting issues that would have been caught by running this command.

If you're already versed in our style guide, then this may not feel necessary, but this command will catch all of that stuff automatically, and I think it will save significant review time to have it here.

Suggest just link the style conventions rather than suggest a specific way of checking adherence. We don't run these tests ourselves, so its pretty confusing to include here.

A lot of things are ignored right now, but flake8 linting does run these tests in this manner.

... learn something new every day!

story645 · 2020-08-24T21:05:31Z

.github/PULL_REQUEST_TEMPLATE.md

+- [ ] New features are documented, with examples if plot related.
+- [ ] Documentation is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error).
+- [ ] Conforms to Matplotlib style conventions (install `flake8-docstrings` and `pydocstyle<4` and run `flake8 --docstring-convention=all`).
+- [ ] New features have an entry in `doc/users/next_whats_new/` (follow instructions in README.rst there).


don't need the there

I think without it it's ambiguous where to find the README.

Also, this language was already there.

Ugh, it's an ambiguous reference & yes can kick that can down to a different PR.

brunobeltran · 2020-08-24T21:10:37Z

PR Summary

Here it is with Jody's proposed re-org. ~~If anyone opposes or has further reorganization suggestions, then I'll just revert it, since it makes more sense to hash that stuff out in a separate PR, I think.~~

This re-org ended up causing a large amount of white space that wasn't there before. I think we should discuss reorg in a later PR. I reverted these changes.

PR Checklist

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (run flake8 on changed files to check).
New features are documented, with examples if plot related.
- New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
- API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).
Documentation is sphinx and numpydoc compliant (the docs should build without error).
- Conforms to Matplotlib style conventions (install flake8-docstrings and pydocstyle<4 and run flake8 --docstring-convention=all).

QuLogic · 2020-08-24T21:59:59Z

This re-org ended up causing a large amount of white space that wasn't there before. I think we should discuss reorg in a later PR. I reverted these changes.

I think that's because you have a blank line between one of them; that causes all of them to get extra spacing.

brunobeltran · 2020-08-24T23:51:46Z

@jklymak I think you're the only blocker here since there's two approvals (unless you think everyone should have a chance to have eyes on this?)

I agree that this list could be organized more naturally, but I think it would be helpful to have these action items in the checklist now, and the organization discussion is exactly what derailed #17153.

I opened a separate PR to discuss the reorg you request, so that this one stays about adding these actions items or no: #18348. If you agree that this PR passes our docs threshold of "definitely doesn't make the situation worse than before", would you be willing to hit the button as-is?

jklymak · 2020-08-25T04:09:46Z

@brunobeltran I'm not blocking, but thanks for asking!

brunobeltran mentioned this pull request Aug 24, 2020

DOCS: include how to reproduce CI in PR template #17153

Closed

6 tasks

brunobeltran added the Documentation label Aug 24, 2020

brunobeltran force-pushed the simpler-pr-update branch from 088f8f5 to 64bbe13 Compare August 24, 2020 19:17

brunobeltran force-pushed the simpler-pr-update branch 2 times, most recently from f29603f to 68cddd5 Compare August 24, 2020 19:23

DOCS: add action items to PR template

c6e1a38

brunobeltran force-pushed the simpler-pr-update branch from 68cddd5 to c6e1a38 Compare August 24, 2020 19:30

dopplershift approved these changes Aug 24, 2020

View reviewed changes

story645 approved these changes Aug 24, 2020

View reviewed changes

jklymak reviewed Aug 24, 2020

View reviewed changes

story645 reviewed Aug 24, 2020

View reviewed changes

brunobeltran force-pushed the simpler-pr-update branch from 81e3545 to c6e1a38 Compare August 24, 2020 21:12

brunobeltran mentioned this pull request Aug 24, 2020

DOCS: add links and sections to PR template #18348

Closed

7 tasks

QuLogic merged commit bb71b00 into matplotlib:master Aug 25, 2020

QuLogic added this to the v3.4.0 milestone Aug 25, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

DOCS: add action items to PR template #18341

DOCS: add action items to PR template #18341

Uh oh!

brunobeltran commented Aug 24, 2020 •

edited

Loading

Uh oh!

brunobeltran commented Aug 24, 2020 •

edited

Loading

Uh oh!

jklymak Aug 24, 2020

Uh oh!

brunobeltran Aug 24, 2020 •

edited

Loading

Uh oh!

jklymak Aug 24, 2020

Uh oh!

QuLogic Aug 24, 2020

Uh oh!

jklymak Aug 24, 2020

Uh oh!

story645 Aug 24, 2020

Uh oh!

brunobeltran Aug 24, 2020

Uh oh!

story645 Aug 24, 2020

Uh oh!

brunobeltran Aug 24, 2020

Uh oh!

brunobeltran commented Aug 24, 2020 •

edited

Loading

Uh oh!

QuLogic commented Aug 24, 2020

Uh oh!

brunobeltran commented Aug 24, 2020 •

edited

Loading

Uh oh!

jklymak commented Aug 25, 2020

Uh oh!

Uh oh!

Uh oh!

DOCS: add action items to PR template #18341

DOCS: add action items to PR template #18341

Uh oh!

Conversation

brunobeltran commented Aug 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

brunobeltran commented Aug 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brunobeltran Aug 24, 2020 • 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!

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!

brunobeltran commented Aug 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

QuLogic commented Aug 24, 2020

Uh oh!

brunobeltran commented Aug 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jklymak commented Aug 25, 2020

Uh oh!

Uh oh!

brunobeltran commented Aug 24, 2020 •

edited

Loading

brunobeltran commented Aug 24, 2020 •

edited

Loading

brunobeltran Aug 24, 2020 •

edited

Loading

brunobeltran commented Aug 24, 2020 •

edited

Loading

brunobeltran commented Aug 24, 2020 •

edited

Loading