From f6b9b461c7f65be53919b662093b984756a0e766 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 13 Nov 2019 21:14:55 -0600 Subject: [PATCH 1/5] DOC: Start maintainer doc --- doc/source/development/index.rst | 1 + doc/source/development/maintaining.rst | 117 +++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 doc/source/development/maintaining.rst diff --git a/doc/source/development/index.rst b/doc/source/development/index.rst index 1228f00667f3a..a523ae0c957f1 100644 --- a/doc/source/development/index.rst +++ b/doc/source/development/index.rst @@ -13,6 +13,7 @@ Development :maxdepth: 2 contributing + maintaining internals extending developer diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst new file mode 100644 index 0000000000000..21ba8ffe3f379 --- /dev/null +++ b/doc/source/development/maintaining.rst @@ -0,0 +1,117 @@ +.. _maintaining: + +****************** +Pandas Maintenance +****************** + +This guide is for pandas' maintainers. It may also be interesting to contributors +looking to understand the pandas development process and what steps are necessary +to become a maintainer. + +Roles +----- + +Pandas uses two levels of permissions: **triage** and **core** team members. + +Triage members can label and close issues and pull requests. + +Core team members can label and close issues and pull request, and can merge +pull requests. + +Tasks +----- + +Pandas is largely a volunteer project, so these tasks shouldn't be read as +"expectations" of triage and maintainers. + +* Triage newly filed issues (see :ref:`maintaining.triage`) +* Review newly opened pull request +* Respond to updates on existing issues and pull requests + +.. _maintaining.triage: + +Issue Triage +------------ + +The issue tracker is many people's first interaction with the pandas project itself, +beyond just using the library. As such, we want it to be a welcoming, pleasant +experience. + +Here's a typical workflow for triaging a newly opened issue. + +1. **Is the necessary information provided?** + + Ideally reporters would fill out the issue template, but many don't. + If crucial information (like the version of pandas they used), is missing + feel free to ask for that and label the issue with "Needs info". + +2. **Check for duplicates** + + We have many open issues. If a new issue is clearly a duplicate, label the + new issue as "Duplicate" assign the milestone "No Action", and close the issue + with a link to the original issue. Make sure to still thank the reporter, and + encourage them to chime in on the original issue, and perhaps try to fix it. + + If the new issue provides relevant information, such as a better or slightly + different example, add it to the original issue as a comment or an edit to + the original post. + +3. **Is the issue minimal and reproducible**? + + For bug reports, we ask that the reporter provide a minimal reproducible + example. See http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports + for a good explanation. If the example is not reproducible, or if it's + *clearly* not minimal, feel free to ask the reporter if they can provide + and example or simplify the provided one. Do acknowledge that writing + minimal reproducible examples is hard work. If the reporter is struggling, + you can try to write one yourself and we'll edit the original post to include it. + + If a reproducible example can't be provided, add the "Needs info" label. + +4. **Feature Requests** + + Generally, pandas prefers to discuss and design new features in issues, before + a pull request is made. Encourage the submitter to include a proposed API + for the new feature. Having them write a full docstring is a good exercise. + +5. **Usage Questions** + + We prefer that usage questions are asked on StackOverflow. If it's easy to + answer, feel free to link to the relevant documentation section, let them + know that in the future this kind of question should be on StackOverflow, + and close the issue. + +6. **Labels and Milestones** + + Apply the relevant labels. This is a bit of an art, and comes with experience. + Look at similar issues to get a feel for how things are labeled. + + If there issue is clearly defined and the fix seems relatively straightforward, + label the issue as "Good first issue". + + Typically, new issues will be assigned the "Contributions welcome" milestone, + unless it's know that this issue should be addressed in a specific release (say + because it's a large regression). + +Closing Issues +-------------- + +Be delicate here: many people interpret closing an issue as us saying that the +conversation is over. It's typically best to give the reporter some time to +self-close their issue if it's determined that the behavior is not a bug, +or the feature is out of scope. Sometimes reporters just go away though, and +we'll close the issue after the conversation has died. + +Reviewing Pull Requests +----------------------- + +Anybody can review a pull request: regular contributors, triagers, or core-team +members. Here are some guidelines to check. + +* Tests should be in a sensible location. +* New public APIs should be included in ``doc/source/reference/``. +* New / changed API should use the ``versionadded`` or ``versionchanged`` directives in the docstring. +* User-facing changes should have a whatsnew in the appropriate file. +* Regression tests should reference the original GitHub issue number like ``# GH-1234``. + +.. _people: https://github.com/pandas-dev/pandas-governance/blob/master/people.md From 04bee2602c1d6a474eb195a326bfef0bdafd00a1 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 13 Nov 2019 21:20:30 -0600 Subject: [PATCH 2/5] fixup --- doc/source/development/maintaining.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst index 21ba8ffe3f379..d39e22087d047 100644 --- a/doc/source/development/maintaining.rst +++ b/doc/source/development/maintaining.rst @@ -22,11 +22,13 @@ Tasks ----- Pandas is largely a volunteer project, so these tasks shouldn't be read as -"expectations" of triage and maintainers. +"expectations" of triage and maintainers. Rather, they're general descriptions +of what it means to be a maintainer. * Triage newly filed issues (see :ref:`maintaining.triage`) * Review newly opened pull request * Respond to updates on existing issues and pull requests +* Drive discussion and decisions on stalled issues and pull requests .. _maintaining.triage: @@ -102,6 +104,10 @@ self-close their issue if it's determined that the behavior is not a bug, or the feature is out of scope. Sometimes reporters just go away though, and we'll close the issue after the conversation has died. +And keep in mind that closing issues isn't a goal on its own. Our goal is to +make pandas the best it can be. + + Reviewing Pull Requests ----------------------- @@ -109,7 +115,7 @@ Anybody can review a pull request: regular contributors, triagers, or core-team members. Here are some guidelines to check. * Tests should be in a sensible location. -* New public APIs should be included in ``doc/source/reference/``. +* New public APIs should be included somewhere in ``doc/source/reference/``. * New / changed API should use the ``versionadded`` or ``versionchanged`` directives in the docstring. * User-facing changes should have a whatsnew in the appropriate file. * Regression tests should reference the original GitHub issue number like ``# GH-1234``. From 0df8c2f92f6a39888cc69d5b4c6937c3b465fdff Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 14 Nov 2019 08:07:12 -0600 Subject: [PATCH 3/5] added triage guide --- doc/source/development/maintaining.rst | 69 ++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 10 deletions(-) diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst index d39e22087d047..76c344c7bae92 100644 --- a/doc/source/development/maintaining.rst +++ b/doc/source/development/maintaining.rst @@ -8,6 +8,8 @@ This guide is for pandas' maintainers. It may also be interesting to contributor looking to understand the pandas development process and what steps are necessary to become a maintainer. +The main contributing guide is available at :ref:`contributing`. + Roles ----- @@ -47,7 +49,7 @@ Here's a typical workflow for triaging a newly opened issue. If crucial information (like the version of pandas they used), is missing feel free to ask for that and label the issue with "Needs info". -2. **Check for duplicates** +2. **Is this a duplicate issue?** We have many open issues. If a new issue is clearly a duplicate, label the new issue as "Duplicate" assign the milestone "No Action", and close the issue @@ -70,20 +72,24 @@ Here's a typical workflow for triaging a newly opened issue. If a reproducible example can't be provided, add the "Needs info" label. -4. **Feature Requests** +4. **Is this a clearly defined feature request?** Generally, pandas prefers to discuss and design new features in issues, before a pull request is made. Encourage the submitter to include a proposed API - for the new feature. Having them write a full docstring is a good exercise. + for the new feature. Having them write a full docstring is a good way to + pin down specifics. + + We'll need a discussion from several pandas maintainers before deciding whether + the proposal is in scope for pandas. -5. **Usage Questions** +5. **Is this a usage qusetion?** We prefer that usage questions are asked on StackOverflow. If it's easy to answer, feel free to link to the relevant documentation section, let them know that in the future this kind of question should be on StackOverflow, and close the issue. -6. **Labels and Milestones** +6. **What labels and milestones should I add?** Apply the relevant labels. This is a bit of an art, and comes with experience. Look at similar issues to get a feel for how things are labeled. @@ -95,6 +101,8 @@ Here's a typical workflow for triaging a newly opened issue. unless it's know that this issue should be addressed in a specific release (say because it's a large regression). +.. _maintaining.closing: + Closing Issues -------------- @@ -104,10 +112,6 @@ self-close their issue if it's determined that the behavior is not a bug, or the feature is out of scope. Sometimes reporters just go away though, and we'll close the issue after the conversation has died. -And keep in mind that closing issues isn't a goal on its own. Our goal is to -make pandas the best it can be. - - Reviewing Pull Requests ----------------------- @@ -120,4 +124,49 @@ members. Here are some guidelines to check. * User-facing changes should have a whatsnew in the appropriate file. * Regression tests should reference the original GitHub issue number like ``# GH-1234``. -.. _people: https://github.com/pandas-dev/pandas-governance/blob/master/people.md +Cleaning up old Issues +---------------------- + +Every open issue in pandas has a cost. Open issues make finding duplicates harder, +and can make it harder to know what needs to be done in pandas. That said, closing +issues isn't a goal on its own. Our goal is to make pandas the best it can be, +and that's best done by ensuring that the quality of our open issues is high. + +Occasionally, bugs are fixed but the issue isn't linked to in the Pull Request. +In these cases, comment that "This has been fixed, but could use a test." and +label the issue as "Good First Issue". + +If an older issue doesn't follow our issue template, edit the original post to +include a minimal example, the actual output, and the expected output. Uniformity +in issue reports is valuable. + +If an older issue lacks a reproducible example, label it as "Needs Info" and +ask them to provide one (or write one yourself if possible). If one isn't +provide reasonably soon, close it according to the policies in :ref:`maintaining.closing`. + +Cleaning up old Pull Requests +----------------------------- + +Occasionally, contributors are unable to finish off a pull request. +If some time has passed (a week, say) since the last review requesting changes, +gently ask if they're still interested in working on this. If another week or +so passes with no response, thank them for their work and close the pull request. +Comment on the original issue that "There's a stalled PR at #1234 that may be +helpful.", and perhaps label the issue as "Good first issue" if the PR was relatively +close to being accepted. + +Additionally, core-team members can push to contributors branches. This can be +helpful for pushing an important PR across the line, or for fixing a small +merge conflict. + +Becoming a pandas maintainer +---------------------------- + +The full process is outlined in our `governance documents`_. In summary, +we're happy to give triage permissions to anyone who shows interest by +being helpful on the issue tracker. + +The current list of core-team members is at +https://github.com/pandas-dev/pandas-governance/blob/master/people.md + +.. _governance documents: https://github.com/pandas-dev/pandas-governance \ No newline at end of file From ada066423d4f64db5c421e58c45cc495192437b5 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 14 Nov 2019 11:37:17 -0600 Subject: [PATCH 4/5] updates --- doc/source/development/maintaining.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst index 76c344c7bae92..e3764ac8d9e2f 100644 --- a/doc/source/development/maintaining.rst +++ b/doc/source/development/maintaining.rst @@ -20,6 +20,8 @@ Triage members can label and close issues and pull requests. Core team members can label and close issues and pull request, and can merge pull requests. +GitHub publishes the full `list of permissions`_. + Tasks ----- @@ -82,12 +84,14 @@ Here's a typical workflow for triaging a newly opened issue. We'll need a discussion from several pandas maintainers before deciding whether the proposal is in scope for pandas. -5. **Is this a usage qusetion?** +5. **Is this a usage question?** + + We prefer that usage questions are asked on StackOverflow with the pandas + tag. https://stackoverflow.com/questions/tagged/pandas - We prefer that usage questions are asked on StackOverflow. If it's easy to - answer, feel free to link to the relevant documentation section, let them - know that in the future this kind of question should be on StackOverflow, - and close the issue. + If it's easy to answer, feel free to link to the relevant documentation section, + let them know that in the future this kind of question should be on + StackOverflow, and close the issue. 6. **What labels and milestones should I add?** @@ -134,7 +138,7 @@ and that's best done by ensuring that the quality of our open issues is high. Occasionally, bugs are fixed but the issue isn't linked to in the Pull Request. In these cases, comment that "This has been fixed, but could use a test." and -label the issue as "Good First Issue". +label the issue as "Good First Issue" and "Needs Test". If an older issue doesn't follow our issue template, edit the original post to include a minimal example, the actual output, and the expected output. Uniformity @@ -169,4 +173,5 @@ being helpful on the issue tracker. The current list of core-team members is at https://github.com/pandas-dev/pandas-governance/blob/master/people.md -.. _governance documents: https://github.com/pandas-dev/pandas-governance \ No newline at end of file +.. _governance documents: https://github.com/pandas-dev/pandas-governance +.. _list of permissions: https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization \ No newline at end of file From 5772227e187ff0403cb432f85884b955a3495ae9 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Fri, 15 Nov 2019 11:48:54 -0600 Subject: [PATCH 5/5] updates --- doc/source/development/maintaining.rst | 46 +++++++++++++++++--------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst index e3764ac8d9e2f..0d1088cc8a6ca 100644 --- a/doc/source/development/maintaining.rst +++ b/doc/source/development/maintaining.rst @@ -30,28 +30,41 @@ Pandas is largely a volunteer project, so these tasks shouldn't be read as of what it means to be a maintainer. * Triage newly filed issues (see :ref:`maintaining.triage`) -* Review newly opened pull request +* Review newly opened pull requests * Respond to updates on existing issues and pull requests * Drive discussion and decisions on stalled issues and pull requests +* Provide experience / wisdom on API design questions to ensure consistency and maintainability +* Project organization (run / attend developer meetings, represent pandas) + +http://matthewrocklin.com/blog/2019/05/18/maintainer may be interesting background +reading. .. _maintaining.triage: Issue Triage ------------ -The issue tracker is many people's first interaction with the pandas project itself, -beyond just using the library. As such, we want it to be a welcoming, pleasant -experience. Here's a typical workflow for triaging a newly opened issue. -1. **Is the necessary information provided?** +1. **Thank the reporter for opening an issue** + + The issue tracker is many people's first interaction with the pandas project itself, + beyond just using the library. As such, we want it to be a welcoming, pleasant + experience. + +2. **Is the necessary information provided?** Ideally reporters would fill out the issue template, but many don't. If crucial information (like the version of pandas they used), is missing - feel free to ask for that and label the issue with "Needs info". + feel free to ask for that and label the issue with "Needs info". The + report should follow the guidelines in :ref:`contributing.bug_reports`. + You may want to link to that if they didn't follow the template. -2. **Is this a duplicate issue?** + Make sure that the title accurately reflects the issue. Edit it yourself + if it's not clear. + +3. **Is this a duplicate issue?** We have many open issues. If a new issue is clearly a duplicate, label the new issue as "Duplicate" assign the milestone "No Action", and close the issue @@ -62,7 +75,7 @@ Here's a typical workflow for triaging a newly opened issue. different example, add it to the original issue as a comment or an edit to the original post. -3. **Is the issue minimal and reproducible**? +4. **Is the issue minimal and reproducible**? For bug reports, we ask that the reporter provide a minimal reproducible example. See http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports @@ -74,7 +87,10 @@ Here's a typical workflow for triaging a newly opened issue. If a reproducible example can't be provided, add the "Needs info" label. -4. **Is this a clearly defined feature request?** + If a reproducible example is provided, but you see a simplification, + edit the original post with your simpler reproducible example. + +5. **Is this a clearly defined feature request?** Generally, pandas prefers to discuss and design new features in issues, before a pull request is made. Encourage the submitter to include a proposed API @@ -84,7 +100,7 @@ Here's a typical workflow for triaging a newly opened issue. We'll need a discussion from several pandas maintainers before deciding whether the proposal is in scope for pandas. -5. **Is this a usage question?** +6. **Is this a usage question?** We prefer that usage questions are asked on StackOverflow with the pandas tag. https://stackoverflow.com/questions/tagged/pandas @@ -93,12 +109,12 @@ Here's a typical workflow for triaging a newly opened issue. let them know that in the future this kind of question should be on StackOverflow, and close the issue. -6. **What labels and milestones should I add?** +7. **What labels and milestones should I add?** Apply the relevant labels. This is a bit of an art, and comes with experience. Look at similar issues to get a feel for how things are labeled. - If there issue is clearly defined and the fix seems relatively straightforward, + If the issue is clearly defined and the fix seems relatively straightforward, label the issue as "Good first issue". Typically, new issues will be assigned the "Contributions welcome" milestone, @@ -112,7 +128,7 @@ Closing Issues Be delicate here: many people interpret closing an issue as us saying that the conversation is over. It's typically best to give the reporter some time to -self-close their issue if it's determined that the behavior is not a bug, +respond or self-close their issue if it's determined that the behavior is not a bug, or the feature is out of scope. Sometimes reporters just go away though, and we'll close the issue after the conversation has died. @@ -152,8 +168,8 @@ Cleaning up old Pull Requests ----------------------------- Occasionally, contributors are unable to finish off a pull request. -If some time has passed (a week, say) since the last review requesting changes, -gently ask if they're still interested in working on this. If another week or +If some time has passed (two weeks, say) since the last review requesting changes, +gently ask if they're still interested in working on this. If another two weeks or so passes with no response, thank them for their work and close the pull request. Comment on the original issue that "There's a stalled PR at #1234 that may be helpful.", and perhaps label the issue as "Good first issue" if the PR was relatively