PSR Review Workflow

Workflow.md

This has moved to a pull request. Please comment there instead.

PHP-FIG's PSR Review Workflow

To avoid a PSR being rushed through the FIG, or to avoid having those lingering 95% complete PSR's that just never seem to make it to a vote, it has become clear that a review workflow is neccessary.

Each PSR will have an original author and potentially a co-author in some cases. Each PSR must also have two co-sponsors, both of whom are voting members and one of whom is a "coordinator" (they can switch if needs be).

0.) Pre-Draft

The author(s) can work on this anywhere they like, do whatever they like and come up with any ideas they feel are within the scope of the PHP-FIG. Once they are ready to try and get this voted into being a "Draft" PSR they should post on the Mailing List and try to find their two sponsors.

1.) Draft

The author(s) and any contributors can make any changes they see fit via pull requests, comments on GitHub, mailing list threads and IRC. Change is free game here, but it's all to be kept in the authors own fork until it is ready to be progress.

2.) Review

Once a PSR has reached Review the author must create a Pull Request on the official PHP-FIG "fig-standards" repo, on on the master branch in the /proposed folder with a simple filename. No number is assigned to the PSR at this point.

While a PSR remains in Review, changes are limited to wording, typos, clarification, minimal rule addition, etc. The author(s) and sponsors may use their own judgement to control the scope of these changes, and block anything that is felt to be a fundamental change.

3.) Accepted

An Acceptance vote is called when the coordinator feels the Review document is ready to have it's final vote. If this vote passes then the Pull Request is merged, and the document is moved by a FIG member with GitHub access from /proposed to /accepted and assigned a PSR number by incrementing the preview PSR number.

Progress

Initially a vote must be called by the "coordinator" to get the PSR into Draft status, before that it's just a third-party concept.

To progress from Draft to Review, and later Review to Accepted, a vote must be called by the "coordinator" for each stage. If this vote is passed it will progress forwards to the next stage.

Each vote must stick to the Voting Protocol.

If the vote fails the author(s) can use feedback to improve and keep it in Review, then try again for another vote later on. The author(s) also have the option of going back to the drawing board if their ideas are slammed multiple times, meaning they need to tell folks they are back in Draft status.

Attribution / Ownership

Each PSR must contain author(s) and sponsors names listed in the document body. These can be changed if people swap out, but a PSR can never progress unless there are two co-sponsors actively backing the PSR.

This does not need to be policed, if a vote is initiated with the name of a sponsor on the document, that sponsor will have plenty of time to raise their concern. In these instances a vote would be invalidated and a new sponsor must be found before it can be voted upon again (sticking to the two-week wait on votes which is the case for any and all votes, as specified in the Voting Protocol.

You don't close your brackets you open at the end.

I thought I can show you a diff if I fork and make changes but doesn't seem to be the case. I corrected a couple of mistakes in my fork.

Well, this helps: https://gist.github.com/markushausammann/b4e6df998f6651be7d63/revisions

The name of the game is 'spot the differences' ... :P

I like the direction. Awhile back I looked into PEP to see how it handles things. Of particular interest to me was when/how numbers were assigned:

http://www.python.org/dev/peps/pep-0001/

I think that getting a number assigned earlier would be a good thing. That way there is less room for ambiguity. If they are ultimately unsuccessful there is still something out there that people can reference. There are a lot of RFC's and what-not out there that were never approved but they can still be referenced quite easily.

Especially when we have more than one proposal in the works at the same time, talking about PSR-X becomes confusing.

Maybe we could assign a new number upon acquiring two sponsors and moves to a Draft proposal? That way we can say that anything that makes it to Draft ends up with a number and at that point people can talk about it clearly. If we cannot get two sponsors, then it is never assigned a number and it dies a quiet lonely death in obscurity.

This has been moved to a pull request

php-fig/fig-standards#146

@simensen that sounds pretty cool, but I dont want to try and change the entire FIG in one bylaw, that would lead to a much bigger conversation that maybe we can have afterwards. A working nickname then an actual number on acceptance for now seems to be working ok.