Meta proposal

_proposals/pup-0001.md

@@ -0,0 +1,268 @@
+---
+title: PUP Purpose and Guidelines
+author: Brian Bouterse
+created: 13-Feb-2017
+status: Active
+---
+
+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](https://www.redhat.com/archives/pulp-dev/2017-February/msg00014.html),
+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, 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](https://www.python.org/dev/peps/) tracks all approved,
+rejected, and abandoned PUPs.
+
+
+PUP Process
+===========
+
+The overall process is: Pre-proposal -> Authoring -> Announcement ->  Discussion and Feedback ->
+Revision -> Voting -> Decision
+
+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](https://www.redhat.com/mailman/listinfo/pulp-list) is the
+  appropriate place.
+* For changes impacting developers, [pulp-dev](https://www.redhat.com/mailman/listinfo/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.rst` and is formatted using
+[markdown syntax](http://daringfireball.net/projects/markdown/syntax). An entry for the PUP should
+also be entered into the index file.
+
+Submit the PUP using a pull request againt the [PUP dedicated repo](https://github.com/python/peps).
+
+
+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 +1, +0, -0, -1 voting process is used; votes are sent as responses via the
+announcement/discussion 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: "Not the right choice and should definitely not be adopted." This type of feedback must come
+  with a statement of objective concerns explaining what harm will come from adopting the proposal.
+
+Note that votes can come from anyone, not just core devs [#f1]_. This is directly modeled after [the
+Django process](https://docs.djangoproject.com/en/dev/internals/contributing/bugs-and-features/#how-we-make-decisions)
+who modeled their process after the Python and Apache communities.
+
+
+Deciding
+^^^^^^^^
+
+* If an obvious consensus arises via voting, the PUP is ratified.
+* Discussion on the email thread can confirm if consensus is obvious or not.
+* Votes come from anyone, not just core devs [#f1]_.
+* A -1 vote from a core dev [#f1]_ is considered a veto vote and will block ratification until the
+  vote is recast.
+* Core devs are expected to consider and echo serious feedback from the community, especially any -1
+  votes from community members.
+* Consensus is not always possible. If obvious consensus is not reached, then the core devs [#f1]_
+  decide.
+
+
+PUP Requirements
+================
+
+This is a modified version of [the Foreman template](https://github.com/theforeman/rfcs/blob/master/0000-template.md).
+
+::
+
+    ---
+    title: <title goes here>
+    author: <author or authors named>
+    created: dd-mmm-yyyy
+    status: [Active|Approved|Rejected|Abandoned]
+    ---
+
+    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 [#f1]_ 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 [#f1]_ 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](https://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](https://www.python.org/dev/peps/) and
+  [raw](https://github.com/python/peps) form.
+
+
+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
+=========
+
+.. [#f1] A core dev is anyone with the permission to commit to the [platform repo](https://github.com/pulp/pulp/).