Bylaw: PSR Review Workflow #146

Merged
merged 54 commits into from Aug 5, 2013

Conversation

Projects
None yet
7 participants
Contributor

philsturgeon commented Jun 20, 2013

Taken from my gist.

This is still for now a work in progress, so definitely hit me up with improvements, comment inline if its to do with the actual content and keep politics or theory to the mailing list.

@ghost

ghost commented Jun 21, 2013

Can you format this with some hard breaks - it's not possible to read in the browser without scrolling right.

Contributor

philsturgeon commented Jun 21, 2013

Done!

Phil Sturgeon

On Friday, 21 June 2013 at 04:51, Drak wrote:

Can you format this with some hard breaks - it's not possible to read in the browser without scrolling right.


Reply to this email directly or view it on GitHub (#146 (comment)).

Phil Sturgeon and others added some commits Jun 21, 2013

Phil Sturgeon Draft is now when it goes into proposed 0884f7b
Phil Sturgeon Added example meta doc 75d8e58
Phil Sturgeon Added note saying draft is when meta doc happens 073a2ed
Phil Sturgeon Added a line about moving sponsors to contributors b5477a7
Phil Sturgeon Added chosen and alternative approaches 57a8554
Phil Sturgeon Added pros/cons 644676a
Phil Sturgeon More strict on the name of the meta doc f9e648b
@webmozart webmozart Improved the workflow document d0f06c6
Phil Sturgeon Improved sponsor participation explanation 235ef58
Phil Sturgeon Merge pull request #2 from bschussek/workflow-bylaw
WIP Improvements
067c7d4
Phil Sturgeon Changes to pre-draft progression 97f540f
@webmozart webmozart Improved the description of the stages f4ca8d6
@webmozart webmozart clarifications 956b00c
Phil Sturgeon Merge pull request #3 from bschussek/workflow-bylaw
Improved the description of the stages
b89e0c8
Phil Sturgeon Removed RFC uppercase words
This was initially a good idea but ended up sounding like a petulant child in charge of a jungle gym instead of a useful document. This wording doesn't apply to human interaction and should be left to PSRs instead.
7af74c0
@webmozart webmozart added a clarifying comment about comments vs. meta docs 0dc4235
Phil Sturgeon General updates to various bits 5126e4e
Phil Sturgeon Merge pull request #4 from bschussek/workflow-bylaw
added a clarifying comment about comments vs. meta docs
382c4b7
Phil Sturgeon Remove reference to generic PSR-X e554de3
@webmozart webmozart clarified what happens when alternative proposals replace original pr…
…oposals
73daf4d
Phil Sturgeon Merge pull request #5 from bschussek/workflow-bylaw
clarified what happens when alternative proposals replace original proposals
8bf59a1
@webmozart webmozart Uncommented comment that should be there in the final document 52a9a89
@webmozart webmozart fixed typos 88a7538
@webmozart webmozart Improved the meta document description and moved some process-relevan…
…t parts out of that section
3a58419
@webmozart webmozart Turned person listings into bulleted lists 0b59c8c
@webmozart webmozart Improved the meta document description f606541
@webmozart webmozart fixed copy-paste error 637d621
@webmozart webmozart fixed broken sentence in section 3.5 76f156e
@webmozart webmozart Included an example of how an alternative could be listed when the au…
…thor vanishes
3695358
@webmozart webmozart Added term "Entrance Vote" ea0cd98
Phil Sturgeon Merge pull request #6 from bschussek/workflow-bylaw
Improved the meta document description and moved some process-relevant parts out of that section
7a9ece8
Phil Sturgeon Removed old auto-increment PSR numbers d8adbc2
Phil Sturgeon Somebody around here is sexist 041c2ea
Phil Sturgeon Typo 01e7855
@webmozart webmozart use term "entrance vote" d92a9d0
Phil Sturgeon Merge pull request #7 from bschussek/workflow-bylaw
use term "entrance vote"
365bc77
Phil Sturgeon Updated with feedback from Larry fc09955
@Crell Crell Rename Author to Editor, revise role definitions accordingly. 4b69a65
@Crell Crell Trailing whitespace fixes. a4ef46a
@Crell Crell Revise Pre-Draft section to clarify its purpose and that a complete r…
…eady-to-go proposal is not required at this stage.
4bc3120
@Crell Crell Adjust Review section accordingly. 32d7c78
@Crell Crell Complete transition from Author to Editor/Contributor. b5479a9
Phil Sturgeon Merge pull request #8 from Crell/editor-role-revisions
Editor role revisions
There are some changes that need to be made, which Larry agrees with. I'll merge then make them myself.
6197d34
Phil Sturgeon Typos and tweaks to Larry's PR 448bd4e
Phil Sturgeon Sponsor != Contributor 6b8365f
Phil Sturgeon Tweaks to definitions 177015d

@magnusnordlander magnusnordlander and 2 others commented on an outdated diff Jul 17, 2013

bylaws/004-psr-workflow.md
+No PSR number is assigned to the proposal at this point.
+
+The Editor must then locate two voting members to sponsor the proposal, one of whom agrees to be the
+Coordinator. The Editor, Sponsors, and existing additional Contributors if any form the working group
+for the proposal.
+
+The proposal is NOT required to be fully developed at this point, although that is permitted. At
+minimum, it must include a statement of the problem to be solved and basic information on the
+general approach to be taken. Further revision and expansion is expected during the Draft phase.
+
+The Coordinator must initiate an entrance vote to enquire whether the members of PHP-FIG are generally
+interested in publishing a PSR for the proposed subject, even if they disagree with the details of
+the proposal. The coordinator must announce the vote on the Mailing List in a thread titled
+"[VOTE][Entrance] Title of the proposal". The vote must adhere to [the voting protocol][voting].
+
+If the vote passes, the proposal officially enters Draft stage. The proposal receives a PSR number
@magnusnordlander

magnusnordlander Jul 17, 2013

This reads like there can be multiple proposals with the same PSR number. Can there?

@philsturgeon

philsturgeon Jul 17, 2013

Contributor

Nope. Got a suggested change?

Sent from my iPhone

On Jul 17, 2013, at 9:07 AM, Magnus Nordlander notifications@github.com wrote:

In bylaws/004-psr-workflow.md:

+No PSR number is assigned to the proposal at this point.
+
+The Editor must then locate two voting members to sponsor the proposal, one of whom agrees to be the
+Coordinator. The Editor, Sponsors, and existing additional Contributors if any form the working group
+for the proposal.
+
+The proposal is NOT required to be fully developed at this point, although that is permitted. At
+minimum, it must include a statement of the problem to be solved and basic information on the
+general approach to be taken. Further revision and expansion is expected during the Draft phase.
+
+The Coordinator must initiate an entrance vote to enquire whether the members of PHP-FIG are generally
+interested in publishing a PSR for the proposed subject, even if they disagree with the details of
+the proposal. The coordinator must announce the vote on the Mailing List in a thread titled
+"[VOTE][Entrance] Title of the proposal". The vote must adhere to [the voting protocol][voting].
+
+If the vote passes, the proposal officially enters Draft stage. The proposal receives a PSR number
This reads like there can be multiple proposals with the same PSR number. Can there?


Reply to this email directly or view it on GitHub.

@zchrykng

zchrykng Jul 17, 2013

I think the confusion is from the "auto-incremented from the last PSR in the /accepted folder of the repo"

Maybe

auto-incremented from the last accepted or draft PSR, whichever is higher

I am not a great wordsmith, but I think it would be clearer.

Edit: To change the wording a little

@philsturgeon

philsturgeon Jul 17, 2013

Contributor

Ahh this has been resolved already I've just not updated it. We're gonna have a wiki page with statuses.

Sent from my iPhone

On Jul 17, 2013, at 9:17 AM, Zachary King notifications@github.com wrote:

In bylaws/004-psr-workflow.md:

+No PSR number is assigned to the proposal at this point.
+
+The Editor must then locate two voting members to sponsor the proposal, one of whom agrees to be the
+Coordinator. The Editor, Sponsors, and existing additional Contributors if any form the working group
+for the proposal.
+
+The proposal is NOT required to be fully developed at this point, although that is permitted. At
+minimum, it must include a statement of the problem to be solved and basic information on the
+general approach to be taken. Further revision and expansion is expected during the Draft phase.
+
+The Coordinator must initiate an entrance vote to enquire whether the members of PHP-FIG are generally
+interested in publishing a PSR for the proposed subject, even if they disagree with the details of
+the proposal. The coordinator must announce the vote on the Mailing List in a thread titled
+"[VOTE][Entrance] Title of the proposal". The vote must adhere to [the voting protocol][voting].
+
+If the vote passes, the proposal officially enters Draft stage. The proposal receives a PSR number
I think the confusion is from the "auto-incremented from the last PSR in the /accepted folder of the repo"

Maybe

auto-incremented from the highest numbered accepted or draft PSR, whichever is higher

I am not a great wordsmith, but I think it would be clearer.


Reply to this email directly or view it on GitHub.

@magnusnordlander

magnusnordlander Jul 17, 2013

@zchrykng Your proposal sounds good. It also effectively blocks number reuse (so that if there is a draft with e.g. number 19, even if that draft fails and never becomes an accepted PSR, no other proposal would be able to use it, there would simply be a gap in the numbering scheme.

Another issue, upon thinking about it, is that I think we've all been around MySQL too long, since the numbers are just incremented, there's nothing automatic about it :) (i.e. I think it should be "incremented from the last accepted or draft PSR, whichever is higher")

@magnusnordlander

magnusnordlander Jul 17, 2013

@philsturgeon That works too, though the wording should still be changed for it :)

@philsturgeon

philsturgeon Jul 17, 2013

Contributor

@magnusnordlander It will be "incremented from the highest numbered PSR which has passed the Entrance Vote, regardless of the status of that PSR."

Phil Sturgeon and others added some commits Jul 17, 2013

@lsmith77 lsmith77 commented on an outdated diff Jul 22, 2013

bylaws/004-psr-workflow.md
+in the normal way to a PSR. A Sponsor MAY step down to become an Editor for a PSR by posting a
+message to the Mailing List. In this case, a new replacement Sponsor MUST be found for the PSR
+to continue. Should a vote be underway, and a recorded Sponsor for that PSR objects on the basis
+that they are inactive or not a valid Sponsor, this objection SHOULD be made on the Mailing List
+and voting for that PSR WILL immediately be invalidated until such time as a replacement Sponsor
+has been put in place. A proposal can never progress unless there are two Sponsors actively
+sponsoring the proposed PSR. Each Sponsor MUST confirm their sponsorship of a PSR via individual
+email to the Mailing List and a PSR will NOT be deemed sponsored until those emails are delivered.
+
+A Sponsor MAY NOT be the Editor or be listed as a Contributor, but there is of course nothing stopping a Sponsor
+from contributing. A Sponsor MAY step down to become the Editor or a Contributor for a PSR by posting a message
+to the Mailing List. In this case, a new Sponsor must be found. Should a vote be underway with a sponsor who
+does not consider themselves active listed in the meta document, they should raise an objection on the Mailing
+List. The vote will then be invalidated until a new sponsor has been put in place.
+
+> Requiring two Sponsors instead of just prevents a single sponsor from making important decisions alone.
@lsmith77

lsmith77 Jul 22, 2013

Contributor

just one .. ?

@lsmith77 lsmith77 and 1 other commented on an outdated diff Jul 22, 2013

bylaws/004-psr-workflow.md
+to see the PSR through the review process. The Editor(s) are not required to be voting members of
+PHP-FIG. If the Editor(s) of a proposal are missing for more than 60 days without notice then
+the Sponsors may agree upon a new Editor. An Editor is assumed to also be a Contributor to a PSR.
+
+**Sponsor:** Any one of two voting members who have agreed to sponsor a proposed PSR.
+Each PSR MUST have two Sponsors. A Sponsor MAY NOT be an Editor but MAY otherwise contribute
+in the normal way to a PSR. A Sponsor MAY step down to become an Editor for a PSR by posting a
+message to the Mailing List. In this case, a new replacement Sponsor MUST be found for the PSR
+to continue. Should a vote be underway, and a recorded Sponsor for that PSR objects on the basis
+that they are inactive or not a valid Sponsor, this objection SHOULD be made on the Mailing List
+and voting for that PSR WILL immediately be invalidated until such time as a replacement Sponsor
+has been put in place. A proposal can never progress unless there are two Sponsors actively
+sponsoring the proposed PSR. Each Sponsor MUST confirm their sponsorship of a PSR via individual
+email to the Mailing List and a PSR will NOT be deemed sponsored until those emails are delivered.
+
+A Sponsor MAY NOT be the Editor or be listed as a Contributor, but there is of course nothing stopping a Sponsor
@lsmith77

lsmith77 Jul 22, 2013

Contributor

sorry for not having participated in the creation of this document .. but this point is not very clear to me. i assume it was put here for good reason, but it would be useful to state that reason explicitly.

@philsturgeon

philsturgeon Jul 22, 2013

Contributor

As you read on it says they can contribute, there is just no point having one persons name in there twice. If they are sponsoring you know they are probably contributing, because they're involved.

@lsmith77 lsmith77 commented on an outdated diff Jul 22, 2013

bylaws/004-psr-workflow.md
+incremented from the highest numbered PSR which has passed the Entrance Vote, regardless of the status of
+that PSR. A list of PSRs will be maintained in the [Index of PHP Standard Recommendations][wikiindex] wiki
+page of the [official PHP-FIG "fig-standards" repo][repo], where the PSR entry is to be maintained by the
+Coordinator.
+
+The working group may continue to work on the proposal during the complete voting period.
+
+### 2.2 Draft
+
+The goal of the Draft stage is to discuss and polish a PSR proposal up to the point that it can be
+considered for review by the PHP-FIG voting and non-voting members.
+
+In Draft stage, the Editor(s) and any Contributors may make any changes they see fit via pull requests,
+comments on GitHub, Mailing List threads, IRC and similar tools. Change here is not limited by any strict
+rules, and fundamental rewrites are possible if supported by the Editor(s). Alternative approaches may be
+proposed and discussed at any time. If the Editor and coordinator are convinced that an alternative proposal
@lsmith77

lsmith77 Jul 22, 2013

Contributor

Coordinator with a capital C to be consistent

@lsmith77 lsmith77 commented on an outdated diff Jul 22, 2013

bylaws/004-psr-workflow.md
+considered for review by the PHP-FIG voting and non-voting members.
+
+In Draft stage, the Editor(s) and any Contributors may make any changes they see fit via pull requests,
+comments on GitHub, Mailing List threads, IRC and similar tools. Change here is not limited by any strict
+rules, and fundamental rewrites are possible if supported by the Editor(s). Alternative approaches may be
+proposed and discussed at any time. If the Editor and coordinator are convinced that an alternative proposal
+is superior to the original proposal, then the alternative may replace the original. If the alternative builds
+upon the original, the Editor(s) of the original proposal and the new alternative will be listed as
+Contributors. Otherwise, the Editor(s) of the alternative proposal should be listed as Contributors.
+
+All knowledge gained during Draft stage, such as possible alternative approaches, their implications, pros
+and cons etc. as well as the reasons for choosing the proposed approach must be summarized in the meta
+document. The purpose of this rule is to prevent circular discussions or alternative proposals from
+reappearing once they have been decided on.
+
+When the Editor and sponsors agree that the proposal is ready and that the meta document is objective and
@lsmith77

lsmith77 Jul 22, 2013

Contributor

capital S for Sponsors .. probably a good idea to run some search/replace for the different defined roles.

@lsmith77 lsmith77 commented on an outdated diff Jul 22, 2013

bylaws/004-psr-workflow.md
+proposal. The goal however *is* to have all PHP-FIG members agree on the completeness and objectivity of
+the meta document.
+
+> Individual members of the PHP-FIG should not be permitted to prevent a PSR from being published.
+
+During Review, changes in both the proposal and the meta document are limited to wording, typos, clarification
+etc. The sponsors should use their own judgement to control the scope of these changes, and must block
+anything that is felt to be a fundamental change. The sponsors must make changes that the majority of the
+PHP-FIG members agree on, even if they personally disagree.
+
+> Sponsors must not block the development of the proposal.
+
+In this stage, major additions to the meta document are strictly prohibited. If alternative approaches are
+discovered that are not yet listed in the meta document, the coordinator must abort the Review by publishing
+a thread titled "[CANCEL REVIEW] PSR-N: Title of the proposal" on the Mailing List, unless the acceptance vote
+has started already. However, the sponsors may choose to abort the vote and the Review even after that,
@lsmith77

lsmith77 Jul 22, 2013

Contributor

how is a vote supposed to be aborted?

@lsmith77 lsmith77 and 1 other commented on an outdated diff Jul 22, 2013

bylaws/004-psr-workflow.md
+if they agree that this is necessary. The purpose of this rule is to give PHP-FIG members the chance
+to consider *all* known alternatives during the Review stage.
+
+Unless a proposal is moved to Draft stage again, it must remain in Review stage for a minimum of two weeks
+before an acceptance vote is called. This gives every PHP-FIG Member sufficient time to get familiar
+with and influence a proposal before the final vote is called.
+
+When the Editor(s) and sponsors agree that the proposal is ready to become a PSR, an acceptance vote is called.
+The coordinator must publish a thread on the Mailing List with the subject "[VOTE][Accept] PSR-N: Title of the proposal"
+to announce the vote. The vote must adhere to [the voting protocol][voting].
+
+### 2.4 Accepted
+
+If the acceptance vote passes, then the proposal officially becomes an accepted PSR. The proposal itself is moved
+from `/proposed` to `/accepted` by a PHP-FIG member with GitHub access and prefixed with its PSR number, such as
+"PSR-4-autoloader.md". Comments must be removed from this document, but a copy of the commented proposal must be kept
@lsmith77

lsmith77 Jul 22, 2013

Contributor

why use a PSR here as an example that has not yet passed?

@philsturgeon

philsturgeon Jul 22, 2013

Contributor

Why not?

Sent from my iPhone

On Jul 22, 2013, at 7:14 AM, Lukas Kahwe Smith notifications@github.com wrote:

In bylaws/004-psr-workflow.md:

+if they agree that this is necessary. The purpose of this rule is to give PHP-FIG members the chance
+to consider all known alternatives during the Review stage.
+
+Unless a proposal is moved to Draft stage again, it must remain in Review stage for a minimum of two weeks
+before an acceptance vote is called. This gives every PHP-FIG Member sufficient time to get familiar
+with and influence a proposal before the final vote is called.
+
+When the Editor(s) and sponsors agree that the proposal is ready to become a PSR, an acceptance vote is called.
+The coordinator must publish a thread on the Mailing List with the subject "[VOTE][Accept] PSR-N: Title of the proposal"
+to announce the vote. The vote must adhere to [the voting protocol][voting].
+
+### 2.4 Accepted
+
+If the acceptance vote passes, then the proposal officially becomes an accepted PSR. The proposal itself is moved
+from /proposed to /accepted by a PHP-FIG member with GitHub access and prefixed with its PSR number, such as
+"PSR-4-autoloader.md". Comments must be removed from this document, but a copy of the commented proposal must be kept
why use a PSR here as an example that has not yet passed?


Reply to this email directly or view it on GitHub.

@lsmith77

lsmith77 Jul 22, 2013

Contributor

just seems to cause confusion when someone wants to look up the example.

@philsturgeon

philsturgeon Jul 22, 2013

Contributor

Fair, as an example it was meant to be an example of one that you'd create - as people can already see existing file names, but i'll switch it to PSR-3 for the sake of simplicity.

Phil Sturgeon Feedback implemented from @lsmith77
This is mostly typos, clarification, capitalization standardization and some word-wrapping improvements.
72ce49d

philsturgeon referenced this pull request Jul 31, 2013

Closed

URI proposal #104

Contributor

philsturgeon commented Aug 5, 2013

The Vote Thread on the ML has resulted in the vote/PR passing. The bylaw is now in effect.

philsturgeon merged commit c0ba314 into php-fig:master Aug 5, 2013

philsturgeon deleted the unknown repository branch Aug 20, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment