Skip to content

PDEP-1 Revision (Decision Making) #53576

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 19 commits into from
Apr 1, 2024
Merged

PDEP-1 Revision (Decision Making) #53576

Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
a9c499d
adding voting draft
noatamir May 3, 2023
233c03e
new workflow intro
noatamir May 3, 2023
45c95fc
update after feedback
noatamir May 10, 2023
0133e82
fix errors
noatamir May 10, 2023
4ad9f80
fix errors
noatamir May 10, 2023
8108b43
Merge branch 'pandas-dev:main' into pdep_voting_wip
noatamir Jun 9, 2023
2b3c5ad
Apply suggestions from code review
noatamir Jun 9, 2023
9092668
clarification
noatamir Jun 14, 2023
a737034
updated based on feedback
noatamir Jun 16, 2023
a59e759
updated based on feedback
noatamir Jun 16, 2023
48b3300
typo
noatamir Jun 16, 2023
32fce5e
Updated following Simon's feedback
noatamir Jul 9, 2023
0530d29
Apply suggestions from code review
jorisvandenbossche Feb 23, 2024
288e005
Merge remote-tracking branch 'upstream/main' into pdep_voting_wip
jorisvandenbossche Feb 23, 2024
809ae6f
change majority to 70%
jorisvandenbossche Feb 23, 2024
d5a1869
some small formatting changes
jorisvandenbossche Feb 23, 2024
88a7db9
reword case of early vote
jorisvandenbossche Feb 23, 2024
97ba480
use Irv's suggestion to reword notifications
jorisvandenbossche Mar 5, 2024
e18db08
add withdrawn status
jorisvandenbossche Mar 6, 2024
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
101 changes: 92 additions & 9 deletions web/pandas/pdeps/0001-purpose-and-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[#51417](https://github.com/pandas-dev/pandas/pull/51417)
- Author: [Marc Garcia](https://github.com/datapythonista),
[Noa Tamir](https://github.com/noatamir)
- Revision: 2
- Revision: 3

## PDEP definition, purpose and scope

Expand Down Expand Up @@ -56,12 +56,24 @@ advisor on the PDEP when it is submitted to the PDEP repository.

### Workflow

#### Rationale

Our workflow was created to support and enable a consensus seeking process, and to provide clarity,
for current and future authors, as well as voting members. It is not a strict policy, and we
discourage any interpretation which seeks to take advantage of it in a way that could "force" or
"sneak" decisions in one way or another. We expect and encourage transparency, active discussion,
feedback, and compromise from all our community members.

#### PDEP States

The possible states of a PDEP are:

- Draft
- Under discussion
- Accepted
- Implemented
- Rejected
- Withdrawn

Next is described the workflow that PDEPs can follow.

Expand All @@ -71,16 +83,75 @@ Proposing a PDEP is done by creating a PR adding a new file to `web/pdeps/`.
The file is a markdown file, you can use `web/pdeps/0001.md` as a reference
for the expected format.

The initial status of a PDEP will be `Status: Under discussion`. This will be changed to
`Status: Accepted` when the PDEP is ready and has the approval of the core team.
The initial status of a PDEP will be `Status: Draft`. This will be changed to
`Status: Under discussion` by the author(s), when they are ready to proceed with the decision
making process.

#### Accepted PDEP
#### PDEP Discussion Timeline

A PDEP discussion will remain open for up to 60 days. This period aims to enable participation
from volunteers, who might not always be available to respond quickly, as well as provide ample
time to make changes based on suggestions and considerations offered by the participants.
Similarly, the following voting period will remain open for 15 days.

To enable and encourage discussions on PDEPs, we follow a notification schedule. At each of the
following steps, the pandas team, and the pandas-dev mailing list are notified via GitHub and
E-mail:

- Once a PDEP is ready for discussion.
- After 30 days, with a note that there is at most 30 days remaining for discussion,
and that a vote will be called for if no discussion occurs in the next 15 days.
- After 45 days, with a note that there is at most 15 days remaining for discussion,
and that a vote will be called for in 15 days.
- Once the voting period starts, after 60 days or in case of an earlier vote, with 15 days
remaining for voting.
- After 10 voting days, with 5 days remaining for voting.

After 30 discussion days, in case 15 days passed without any new unaddressed comments,
the authors may close the discussion period preemptively, by sending an early reminder
of 15 days remaining until the voting period starts.

#### Casting Votes

As the voting period starts, a VOTE issue is created which links to the PDEP discussion pull request.
Each voting member, including author(s) with voting rights, may cast a vote by adding one of the following comments:

- +1: approve.
- 0: abstain.
Copy link
Member

Choose a reason for hiding this comment

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

Do we want to add a small explanation of how we understand "abstaining" or what it could mean?
Something like "Not fully convinced, but don't want to block it", or better worded (although there might be many reasons to vote +0, like "I haven't closely followed, but trust the majority")

Copy link
Member Author

Choose a reason for hiding this comment

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

Isn't that the one sentence reason thing on the next line?
Formally, it is anyone who wants the vote to proceed (achieve quorum), but not interested in voting for or against it. But that's kind of the dictionary definition almost no?!

- Reason: A one sentence reason is required.
- -1: disapprove
- Reason: A one sentence reason is required.

A disapprove vote requires prior participation in the PDEP discussion issue.
Copy link
Contributor

Choose a reason for hiding this comment

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

Would it not be sufficient for a voting member to follow a discussion led by knowledgeable parties and simply provide a vote that read: "-1: disapprove. I agree with XXX's analysis and concerns and disagree that YYY's argument and the PDEP are suitable".

Rather than provide rules that restrict voting in certain ways (which might be difficult to police anyway), would it not be sufficient to design quorum and majority rules that aim to progress PDEPs that have garnered 'sufficient' support (whatever that may end up being), above objections.

Copy link
Contributor

Choose a reason for hiding this comment

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

Would it not be sufficient for a voting member to follow a discussion led by knowledgeable parties and simply provide a vote that read: "-1: disapprove. I agree with XXX's analysis and concerns and disagree that YYY's argument and the PDEP are suitable".

They could post that in the PDEP discussion issue, and then cast their vote that way in the voting issue.

Rather than provide rules that restrict voting in certain ways (which might be difficult to police anyway), would it not be sufficient to design quorum and majority rules that aim to progress PDEPs that have garnered 'sufficient' support (whatever that may end up being), above objections.

I think our goal here was to avoid the case where we have one or two people who oppose a PDEP stop the PDEP from moving forward. If you have an idea on how to improve what we've proposed, we'd certainly be open to that.


A PDEP can only be accepted by the core development team, if the proposal is considered
worth implementing. Decisions will be made based on the process detailed in the
[pandas governance document](https://github.com/pandas-dev/pandas-governance/blob/master/governance.md).
In general, more than one approval will be needed before the PR is merged. And
there should not be any `Request changes` review at the time of merging.
Comments made on the public VOTE issue by non-voting members will be deleted.

Once the voting period ends, any voter may tally the votes in a comment, using the format: w-x-y-z,
where w stands for the total of approving, x of abstaining, y of disapproving votes cast, and z
of number of voting members who did not respond to the VOTE issue. The tally of the votes will state
if a quorum has been reached or not.

#### Quorum and Majority

For a PDEP vote to result in accepting the proposal, a quorum is required. All votes (including
abstentions) are counted towards the quorum. The quorum is computed as the lower of these two
values:

- 11 voting members.
- 50% of voting members.

Given a quorum, a majority of 70% of the non-abstaining votes is required as well, i.e. 70% of
the approving and disapproving votes must be in favor.

Thus, abstaining votes count towards a quorum, but not towards a majority. A voting member might
choose to abstain when they have participated in the discussion, have some objections to the
proposal, but do not wish to stop the proposal from moving forward, nor indicate their full
support.

If a quorum was not reached by the end of the voting period, the PDEP is not accepted. Its status
will change to rejected.

#### Accepted PDEP

Once a PDEP is accepted, any contributions can be made toward the implementation of the PDEP,
with an open-ended completion timeline. Development of pandas is difficult to understand and
Expand Down Expand Up @@ -109,6 +180,17 @@ discussion. A PDEP can be rejected for different reasons, for example good ideas
that are not backward-compatible, and the breaking changes are not considered worth
implementing.

The PDEP author(s) can also decide to withdraw the PDEP before a final decision
is made (`Status: Withdrawn`), when the PDEP authors themselves have decided
that the PDEP is actually a bad idea, or have accepted that it is not broadly
supported or a competing proposal is a better alternative.

The author(s) may choose to resubmit a rejected or withdrawn PDEP. We expect
authors to use their judgement in that case, as to whether they believe more
discussion, or an amended proposal has the potential to lead to a different
result. A new PDEP is then created, which includes a link to the previously
rejected PDEP.

#### Invalid PDEP

For submitted PDEPs that do not contain proper documentation, are out of scope, or
Expand Down Expand Up @@ -184,6 +266,7 @@ hope can help clarify our meaning here:

- 3 August 2022: Initial version ([GH-47938][47938])
- 15 February 2023: Version 2 ([GH-51417][51417]) clarifies the scope of PDEPs and adds examples
- 09 June 2023: Version 3 ([GH-53576][53576]) defines a structured decision making process for PDEPs

[7217]: https://github.com/pandas-dev/pandas/pull/7217
[8074]: https://github.com/pandas-dev/pandas/issues/8074
Expand Down