Skip to content
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

PDEP-1 Revision (Decision Making) #53576

Merged
merged 19 commits into from
Apr 1, 2024
Merged

PDEP-1 Revision (Decision Making) #53576

Changes from 12 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
88 changes: 79 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,8 +56,19 @@ 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
Expand All @@ -71,16 +82,69 @@ 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 discussion days, with 30 days remaining for discussion.
- After 45 discussion days, with 15 days remaining for discussion.
- In case 15 days passed without any new unaddressed comments, the authors may close the discussion period
Copy link
Member

Choose a reason for hiding this comment

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

I have a question about this: Is it required to give notice that the voting will start in x days or can you just say voting starts now? This is a bit confusing if that happens very early because discussion did not gain traction.

Copy link
Contributor

Choose a reason for hiding this comment

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

The concept is that you can say "voting starts now"

Copy link
Member

Choose a reason for hiding this comment

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

Can we require at least a discussion period of 3 weeks? I was a bit surprised that this was already ready. Granted, it was my fault to not object to the 75% majority earlier (or follow up on my comment above), but I expected that I'd have more time.

My reasoning here is: Get a earliest moment in time when the voting procedure could possibly start

Copy link
Contributor

Choose a reason for hiding this comment

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

Well, the way it is written is that if there is no discussion for 15 days, you could call for a vote. So in theory, if there was no discussion for 15 days right after a PDEP was created, the author could call for a vote, but I think that is highly unlikely.

Or we can say that there is a minimum discussion period of 3 weeks, as you suggest.

Copy link
Member

Choose a reason for hiding this comment

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

I'd like the 3 weeks, it seems like a low requirement as you said and would make things clearer. I previously assumed that it would require at least 45 days of discussion (that was on me though).

Copy link
Member

Choose a reason for hiding this comment

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

Can we require at least a discussion period of 3 weeks? I was a bit surprised that this was already ready.

FWIW, this PR wasn't necessarily "ready", it's just that my question if there were more comments triggered people to start approving ..

But +1 on requiring at least 3 weeks (which already had passed in this case, though)

Copy link
Member Author

Choose a reason for hiding this comment

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

Suggested change
- In case 15 days passed without any new unaddressed comments, the authors may close the discussion period
- After 45 days, in case 15 days passed without any new unaddressed comments, the authors may close the discussion period

Copy link
Member Author

Choose a reason for hiding this comment

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

This suggests a 30 days minimum active discussion period, before an early vote can be triggered.

Copy link
Member

Choose a reason for hiding this comment

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

Since there is a requirement to participate in order to downvote, then we could have a situation where a discussion has not had any objections and proceeding to a vote would be pointless since only those in support could vote.

This is maybe not a bad thing as it puts the onus on members to get involved in the discussion early.

Extending the minimum discussion period is a potential solution to give sufficient opportunity to participate, but it maybe that we should have a notice period for the vote to begin. "voting starts now" is a bit final.

Copy link
Member

Choose a reason for hiding this comment

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

to avoid this then maybe we should just remove the requirement to participate in the discussion in order to be able to downvote

Copy link
Member

Choose a reason for hiding this comment

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

Extending the minimum discussion period is a potential solution to give sufficient opportunity to participate, but it maybe that we should have a notice period for the vote to begin. "voting starts now" is a bit final.

It's a good point that when a discussion has been quiet, being able to just "start the voting" with an early vote, sounds a bit abrupt (exactly because the discussion went quiet, people might have forgotten about commenting on the PDEP).

I updated the text around this slightly to just state in general that we expect a notification 15 days before a vote would start. And then this heads up for a nearing vote can either be after 30 days for an early vote (so the end result is the same as Noa's suggestion above that the actual cote can happen after 45 days) or later.

Copy link
Member

Choose a reason for hiding this comment

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

Thanks @jorisvandenbossche

We use the term "unaddressed comment" in the proposal. I changed my review here to "requires changes" recently because of this.

Now, IIRC in the discussion about PDEP-8 (i've not checked the timelines thoroughly and it maybe that I should use a hypothetical case instead) that we had potentially progressed to the vote with unaddressed comments.

Any ideas to cover this scenario or whether we need to at this stage?

Copy link
Contributor

@Dr-Irv Dr-Irv Feb 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Suggested change
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 discussion days, with 30 days remaining for discussion.
- After 45 discussion days, with 15 days remaining for discussion.
- In case 15 days passed without any new unaddressed comments, the authors may close the discussion period
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, with an indication that a voting period will commence after 15 days of the notification date if there is no further discussion:
- Once a PDEP is ready for discussion.
- After 30 discussion days, with 30 days remaining for discussion.
- After 45 discussion days, with 15 days remaining for discussion.

Copy link
Member

Choose a reason for hiding this comment

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

@Dr-Irv I pushed a different commit with an attempt to address the same thing, see 88a7db9. Can you take a look at that?

Copy link
Contributor

Choose a reason for hiding this comment

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

@jorisvandenbossche I looked at just that commit and made a comment on that text.

preemptively, and open the voting period.
- 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.

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


Comments made on the public VOTE issue by non-voting members will be deleted.

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.
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, z 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 75% of the non-abstaining votes is required as well, i.e. 75% 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 +173,11 @@ 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 author(s) may choose to resubmit a rejected 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 +253,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
Loading