Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
253 lines (154 sloc) 8.8 KB
title author Version created Last-Modified status
PUP Purpose and Guidelines
Brian Bouterse
4
13-Feb-2017
13-Aug-2017
Approved

Summary

This proposal provides a structured process to propose, track, discuss, and decide on process changes for the Pulp project and community.

Motivation

As initially raised on the pulp-dev list, Pulp lacks a process to propose, track, discuss, and decide on changes that affect the Pulp community.

This is a problem that has been addressed by many communities. The process outlined in this document is inspired by processes in the Python, Django, CentOS, and Foreman communities.

What are these called?

These documents are called Pulp Update Proposals or a "PUP" for short.

Tracking PUPs

An index mimicking the Python PEP index tracks all approved, rejected, and abandoned PUPs.

PUP Process

The overall process is: Pre-proposal -> Authoring -> Announcement -> Discussion and Feedback -> Revision -> Voting -> Accepting/Rejecting

Most of the process is facilitated using either the pulp-list or pulp-dev mailing lists. The following guidelines identify how they should.

  • For changes impacting users, pulp-list is the appropriate place.
  • For changes impacting developers, pulp-dev is the appropriate place.

Pre-Proposal

Discussing an idea via the appropriate mailing list prior to writing a formal PUP is encouraged. This is intended to save the author time by gathering feedback quickly before writing a concrete, detailed proposal.

Authoring and Submission

The PUP is a single file, e.g. pup-0022.md and is formatted using markdown syntax. An entry for the PUP should also be entered into the index file.

Submit the PUP using a pull request against the PUP dedicated repo.

Announcement

Once a PUP pull request is created, an announcement should be sent to the appropriate list, which would include a very brief introduction and a link to the pull request. The announcement must also include a must-respond-by date and time for voting.

Discussion and Feedback

General discussion would occur on the announcement thread on the appropriate mailing list. Threaded e-mail readers should make this conversation format easy to follow, while keeping the PUP document in-tact and easy to read. Comments may also be left on the pull request directly.

Revision

Revision occurs as additional commits on the pull request from the author or collaborators. The commit messages are expected to identify the changes and improvements made. Collaborators may send additional commits to the pull request either as patches or additional pull requests.

Voting

The lazy consensus model is used for deciding via votes on the mailing list.

The +1, +0, -0, -1 voting process is used; votes are sent as responses via the announcement/discussion thread on the mailing list. The voting has the following meanings:

  • +1: "Will benefit the project and should definitely be adopted."
  • +0: "Might benefit the project and is acceptable."
  • -0: "Might not be the right choice but is acceptable."
  • -1: "I have serious reservations that need to be thought through and addressed."

Accepting/Rejecting

  • A PUP is accepted with two +1 votes from anyone and no blocking -1 votes from core devs.
  • +/- 0 votes inform support or dissent but do not pass or block a PUP. The stated concerns with a -0 vote may influence other people to have blocking reservations.
  • A -1 vote from a core dev [1] is considered a blocking vote and must be accompanied with substantive arguments.
  • Stated concerns with a blocking vote can be used to revise a PUP until the blocking vote is recast or the PUP is withdrawn.
  • Votes can be recast. Common reasons for doing so include on-going discussion or from observing other votes that have been cast. For example, a -1 vote could be recast to a non-blocking vote due to changes that have been made in the PUP to address their concerns. Another example is recasting a vote to a -1 based on observing many -0 votes which indicate a PUP does not have broad support even with enough +1 votes to pass.
  • Votes can come from anyone, not just core devs [1].
  • The PUP author(s) votes are not assumed. PUP author(s) can choose to cast a vote during voting or not.
  • Core devs [1] are expected to consider and echo serious concerns from the community, especially any -1 votes from community members.

PUP Requirements

This is a modified version of the Foreman template.

---
title: <title goes here>
author: <author or authors named>
created: dd-mmm-yyyy
status: [Active|Approved|Rejected|Abandoned]
version: 1
---

## Summary

One paragraph explanation of the PUP.


## Motivation

Why are we doing this? What problem is it designed to solve? What is the expected outcome?


## Detailed Design

This is the bulk of the PUP. Explain the design in enough detail for somebody familiar with the
project to understand, and for somebody familiar with the codebase to implement. This should get
into specifics and corner cases and include examples of how the feature is used.


## Drawbacks

Why should we not do this?


## Alternatives

What other designs have been considered? What is the impact of not doing this?

Be creative here. Brainstorm with others. No idea is too outlandish to mention. Include ideas
that are "obviously" bad; even one sentence about why something was ruled out is valuable.


## Unresolved Questions

What parts of the design are still to be determined?

Reaching a Decision

How Long?

The initial announcement needs to identify a must-respond-by date and time. This should be no less than 12 calendar days from the initial announcement. Longer periods are also OK, and can be adjusted via the list based on feedback via the list.

Why Approve/Reject This Way?

  • It treats community decision making, not just core dev [1] decision making, as a first class principle.
  • The same process works for the best communities we know of (Django, Python, Apache, etc).
  • It allows people to be as involved or not as they desire.
  • It allows serious concerns to not be dismissed due to a -1 vote from core dev [1] being a veto.

Approval

  • The pull request is merged, which introduces the PUP file and the entry into the index in the approved section.
  • A post-approval announcement must be sent in a new thread, not the discussion thread, on the appropriate email list. It must include a link to the approved PUP text. A new thread is used because many users will tune-out on a thread that receives many replies.

Rejected or Abandoned PUPs

  • The PUP pull request is merged, but the entry in the index file lists the PUP in the rejected or abandoned section.
  • The proposal text stays committed and is not removed.

Is This Replacing Story Planning in Redmine?

No. This is for process changes and should not be used to discuss Pulp's feature set or bugs. Feature and bug discussion should continue to occur as-is (on pulp.plan.io).

This is different than the communities we are modeling our the PUP process after. Other communities use it for feature planning also, but current we only use it for process changes.

Examples

  • This proposal
  • All the PEPs in both web and raw form.

Revising Accepted PUPs

Even after a PUP has been accepted, it may be revised. The process for changing a PUP is the same as creating a new PUP. This process starts with a discussion followed by a PR to change the existing PUP. The PR should increment the version number of the PUP by 1. Then a voting period occurs which is decided by lazy consensus. If the vote passes, the PR is then merged.

Drawbacks

  • The history is in two places: the commit history and separately the mailing list archive.
  • Mailing lists can be hard to follow.

Alternatives

We could store the PUPs in Redmine. Why aren't we using Redmine?

Upsides:

  • It would keep every comment and the PUP itself on one webpage.
  • It would be kept along with bugs and stories

Downsides:

  • Redmine isn't great for long, structured documents. For instance linking between sections is hard.
  • Redmine's long conversations become difficult to read
  • Comments don't support threading well.
  • History of Redmine edits is not as clear as a git commit history.

Footnotes

[1]: core dev: A core dev is anyone with the permission to commit to the platform repo.

You can’t perform that action at this time.