Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

DRAFT of a bylaw addressing versioning. #93

Closed
wants to merge 7 commits into from

8 participants

@skyzyx

Proposes guidelines for how to adopt changes to PSRs as necessary.

bylaws/003-superseding-psr.md
((23 lines not shown))
+
+4. All new PSRs that pass the vote MUST receive the next subsequent integer for
+its identifier (e.g., `PSR-0`, `PSR-1`, `PSR-2`, `PSR-3`, ..., `PSR-n`). The
+proposal upon which the PSR is based may cover new ground, or may enhance,
+change or otherwise supercede an existing PSR.
+(For precedent, see [21st amendment to the U.S. Constitution](https://en.wikisource.org/wiki/Additional_amendments_to_the_United_States_Constitution#Amendment_XXI);
+[IETF RFC 1123 Update History](http://www.rfc-editor.org/search/rfc_search_detail.php?rfc=1123).)
+
+5. If the intention of a new proposal is to modify (and thereby supersede) an
+existing PSR, the proposal SHOULD clearly explain as much in its introduction.
+
+6. If a superceding proposal (as per paragraph 5) is adopted as a new PSR, the
+PSR which was superceded continues to be a valid PSR, although it ceases to be
+"recommended". The superseding PSR(s) will inherit the "recommended" status, and
+the superseded PSR(s) will be clarified (as per paragraph 2) to direct readers
+to the superseding PSR(s).
@skyzyx
skyzyx added a note

I'm not totally sold on paragraph 6, here. What are the possible use-cases we anticipate?

This doesn't happen for IETF RFCs, nor does it happen with HTML specifications (simply referencing other organizations I've observed; nothing more), but this group seems to lean toward wanting to have the one true recommendation.

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

this mimics pretty much what I was thinking. I think the barrier for clarification changes could be a bit higher. also there is a typo in 2. "made be made" (couldn't convince the Gibb hi to give me an online form on my nexus 7)

@skyzyx

@lsmith77: Fair enough about clarification changes. I simply looked at existing patterns within the group. If you believe the barrier should be higher, what do you propose?

@lsmith77
@ghost Show outdated diff Hide outdated diff Unknown commented on an outdated diff
bylaws/003-superseding-psr.md
((25 lines not shown))
+its identifier (e.g., `PSR-0`, `PSR-1`, `PSR-2`, `PSR-3`, ..., `PSR-n`). The
+proposal upon which the PSR is based may cover new ground, or may enhance,
+change or otherwise supercede an existing PSR.
+(For precedent, see [21st amendment to the U.S. Constitution](https://en.wikisource.org/wiki/Additional_amendments_to_the_United_States_Constitution#Amendment_XXI);
+[IETF RFC 1123 Update History](http://www.rfc-editor.org/search/rfc_search_detail.php?rfc=1123).)
+
+5. If the intention of a new proposal is to modify (and thereby supersede) an
+existing PSR, the proposal SHOULD clearly explain as much in its introduction.
+
+6. If a superceding proposal (as per paragraph 5) is adopted as a new PSR, the
+PSR which was superceded continues to be a valid PSR, although it ceases to be
+"recommended". The superseding PSR(s) will inherit the "recommended" status, and
+the superseded PSR(s) will be clarified (as per paragraph 2) to direct readers
+to the superseding PSR(s).
+
+7. It is possible for one new proposal to update multiple PSRs. (e.g., a future
@ghost
ghost added a note

No comma after e.g.

@skyzyx
skyzyx added a note
  • Chicago Manual of Style: A comma is usually used after i.e. and e.g.
  • Blue Book of Grammar and Punctuation: Commas are preferable/optional after the abbreviations.
  • The Columbia Guide to Standard American English: [Editors] require a comma after the second period [in these abbreviations].
  • The Guide to Grammar and Writing: The comma [following i.e. and e.g.] makes good sense.
  • Lynch Guide to Grammar: Both abbreviations should be followed by a comma.
  • Fowler's Modern English Usage: Commas do not usually follow i.e. (No comment on e.g.)

[Source]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ghost Show outdated diff Hide outdated diff Unknown commented on an outdated diff
bylaws/003-superseding-psr.md
((28 lines not shown))
+(For precedent, see [21st amendment to the U.S. Constitution](https://en.wikisource.org/wiki/Additional_amendments_to_the_United_States_Constitution#Amendment_XXI);
+[IETF RFC 1123 Update History](http://www.rfc-editor.org/search/rfc_search_detail.php?rfc=1123).)
+
+5. If the intention of a new proposal is to modify (and thereby supersede) an
+existing PSR, the proposal SHOULD clearly explain as much in its introduction.
+
+6. If a superceding proposal (as per paragraph 5) is adopted as a new PSR, the
+PSR which was superceded continues to be a valid PSR, although it ceases to be
+"recommended". The superseding PSR(s) will inherit the "recommended" status, and
+the superseded PSR(s) will be clarified (as per paragraph 2) to direct readers
+to the superseding PSR(s).
+
+7. It is possible for one new proposal to update multiple PSRs. (e.g., a future
+`PSR-99` might update both `PSR-1` and `PSR-2`.)
+
+8. It is possible for multiple proposals to update a single PSR. (e.g., multiple
@ghost
ghost added a note

No comma after e.g.

@skyzyx
skyzyx added a note

See above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
bylaws/003-superseding-psr.md
((26 lines not shown))
+proposal upon which the PSR is based may cover new ground, or may enhance,
+change or otherwise supercede an existing PSR.
+(For precedent, see [21st amendment to the U.S. Constitution](https://en.wikisource.org/wiki/Additional_amendments_to_the_United_States_Constitution#Amendment_XXI);
+[IETF RFC 1123 Update History](http://www.rfc-editor.org/search/rfc_search_detail.php?rfc=1123).)
+
+5. If the intention of a new proposal is to modify (and thereby supersede) an
+existing PSR, the proposal SHOULD clearly explain as much in its introduction.
+
+6. If a superceding proposal (as per paragraph 5) is adopted as a new PSR, the
+PSR which was superceded continues to be a valid PSR, although it ceases to be
+"recommended". The superseding PSR(s) will inherit the "recommended" status, and
+the superseded PSR(s) will be clarified (as per paragraph 2) to direct readers
+to the superseding PSR(s).
+
+7. It is possible for one new proposal to update multiple PSRs. (e.g., a future
+`PSR-99` might update both `PSR-1` and `PSR-2`.)

I don't think "update" is quite the right word here. Maybe "extend or supersede"?

@skyzyx
skyzyx added a note

Good point. The language should remain consistent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ghost Show outdated diff Hide outdated diff Unknown commented on an outdated diff
bylaws/003-superseding-psr.md
((13 lines not shown))
+
+2. Changes to an existing PSR may be made only for the purpose of clarifying
+the specification, not for adding new features or changing the meaning of the
+PSR in **any** way. These types of changes MUST be discussed on one of the
+sanctioned discussion lists for the group, and MUST have a motion and a second
+by 2 or more voting members.
+(See "[second voting member agrees](https://github.com/php-fig/fig-standards/pull/56#issuecomment-11905115)".)
+
+3. Subsequent work should happen in an entirely new proposal. Each new proposal
+must pass through all appropriate [voting protocols](001-voting-protocol.md) adopted by the group.
+
+4. All new PSRs that pass the vote MUST receive the next subsequent integer for
+its identifier (e.g., `PSR-0`, `PSR-1`, `PSR-2`, `PSR-3`, ..., `PSR-n`). The
+proposal upon which the PSR is based may cover new ground, or may enhance,
+change or otherwise supercede an existing PSR.
+(For precedent, see [21st amendment to the U.S. Constitution](https://en.wikisource.org/wiki/Additional_amendments_to_the_United_States_Constitution#Amendment_XXI);
@ghost
ghost added a note

Examples of precedent should be kept in theme, so only technical specification orgs, IETF, IEEE, W3C etc. The US constitution is out of theme here.

@skyzyx
skyzyx added a note

Fair enough.

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

@lsmith77

the question is why should the barrier we lower than a normal vote?

IMO, clarification of language without changing meaning is a copyediting task. People with copyediting experience are better capable of making these decisions than those who do not. It just doesn't seem like the kind of thing which should need all the overhead of a "full" vote.

Do you disagree?

@lsmith77
@eddieajau

So, I fiddled around with it and this is what I came up with:

https://gist.github.com/eddieajau/2a74cf81d0055e084b06

I think that boils it down to the bare minimum we need to operate. The text is below to save you hitting the link:

PHP Specification Requests (PSRs)

Having a settled specification allows those who choose to adopt these recommendations to have a solid foundation from which to build. The intention of this bylaw is to add guidelines around how to address changes to our
recommendations.

This document is based (in spirit) on the work of the RSS Advisory Board and the patterns established by the IETF.

  1. All voting in conjunction with PSRs is to be carried out in accordance with the voting protocol.
  2. Anyone can propose a draft PSR for discussion, but only voting members can call for a vote to adopt a PSR in final form.
  3. PSRs are not binding to any person, organisation or entity. They are recommendations only.
  4. A PSR passed by vote adopts the next available subsequent integer for its identifier (for example, PSR-0, PSR-1, PSR-2, PSR-3, ..., PSR-n).
  5. If a PSR is passed by vote, it cannot be changed except to make minor changes to the text the purpose of clarity. Any modifications what would result in a change to the meaning of the PSR requires that a new PSR be considered.
  6. A new PSR may reference, require or expand on one or more previously accepted PSRs.
  7. A new PSR may supercede an exsisting PSR. In this case, both PSR are still considered "accepted", but the superceded PSR is no longer considered "recommended". The superceded PSR will be modified to note which PSR superceded it.
@bobthecow

I'm not sold on the "PSRs can never be changed" thing. It's based on the IETF's policy, but their policy is based on the facts that (1) they have a really long approval process, which involves lots of people actually implementing what has been recommended, before it gets approved and set in stone, and (2) their policy is a ghetto form of revision control, since the RFCs predate things like Git and GitHub making it easy to see previous versions of things.

In my opinion, I would rather see a system based on Python's PEPs. They have "Active" and "Final" PEPs. Their analog to PSR-1/2, PEP-8, is "Active". It can be updated as needs change. It is analogous to IETF's "Best Current Practice" documents, rather than their RFCs. It seems that a coding standard should fall into this camp more than the "once voted on, it's set in stone" camp.

@eddieajau

I'm ok with either approach, just as long as everyone knows where they stand. So how does the "active" and "final" work in practice. Do you have to declare whether it's one or the other when you put it for a vote? Can active become final one day?

@skyzyx

I'm assuming that it's possible for an Active PEP may eventually become a Final PEP. Is this correct? Is that the typical flow for a PEP? Under what circumstances does a PEP move from one status to another?

And while I don't mind normal updates to PSRs, I think they should be subject to normal votes. If we (as a group) are okay with updating PSRs over time as we deem necessary, I'd be happy to go in this direction.

The topic of the day is PSR-2 which has always been, and will always be, controversial. However, calmer minds may find reason to update other PSRs in the future, and I think that's fine.

@bobthecow

I believe they are designated as "active" when they're proposed/approved. PEPs have a lot more process, and more states, than PSRs do at this point, but we probably don't want to jump in and add a lot of process before we know what process we need. But we definitely need more process than we have now :)

Something like this seems reasonable to me:

Say I want to propose a template for future PSRs.

I draft the template, solicit feedback, get a great conversation going on the mailing list, and everyone's stoked about it. We determine that this sort of document is more of a "Current Best Practice", since it'll probably need to be adapted over time. We designate it as "Active" and vote to approve it. When it's approved, it becomes "PSR-4 — A Template for Future PSRs".

At some point in the future, it becomes evident that we missed some things. A revision is drafted, proposed and goes through the whole PSR process. It is approved, it is still "PSR-4 — A Template for Future PSRs", but it's the more current, more best practicey version.

PSR-4 stays in "Active", gradually adjusted to stay relevant. This could be forever, or it could just be until it's deprecated by a brand new and different PSR.

Say I want to propose an API for cryptographic hashing

As before, I go through the proposal process. This one, however, is the sort of thing that happens once, so it's not going to be designated as "Active". When it's approved, it becomes PSR-5.

At this point, its status becomes "Accepted". This means "start building things using this PSR". We can think of this as code freeze. Everything that we could predict would go wrong with this has been covered. The wording all makes sense to us. We give it a green light and libraries start using it.

Over the course of the next n months, the approved PSR is implemented, beat on, and made fun of. But it's not yet set in stone, so to speak. In the event that something unexpected turns up, we can reword things for clarity. We might adjust actual details, too, if the situation warrants it. But we'll do them with the same amount of care as we would changing an API after code freeze.

Once the pre-defined period of time has expired, PSR-5 moves into "Final". At this point, it's canon. Any further changes would require a superseding PSR-N to deprecate this one and replace it with something awesome and new.

@eddieajau
@skyzyx

Short version: I like @bobthecow's idea better than my own. As such, I've rewritten this proposal completely from scratch, taking a different approach to versioning.

If you reviewed this proposal before, please review it again.

@eddieajau

I can get behind that. Two comments:

The title: I think it should just be PSR process or just PSRs (and can we define the acronym)
3.1/3.2: Do we need to set the "pre-defined period"?

@ghost Unknown commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((31 lines not shown))
+
+## PSR Workflow
+
+1. To be considered by the FIG, a PSR draft MUST prepared and proposed for
+discussion and review on the php-fig mailing list. The PSR status at this time
+is _Proposed_. Draft authors SHOULD collect community feedback. Depending on the
+proposal, they MAY conduct polls, or compile relevant statistics on current
+implementations and prior art. Drafts SHOULD be discussed, revised, and amended
+according to the feedback recieved.
+
+2. During the discussion phase, the draft proposal MUST be designated as either
+an _Informational_ proposal, or a _Recommendation Track_ proposal.
+
+3. After sufficient discussion has occured, and draft revision is finalized, a
+voting member MAY call for a vote. The voting process MUST then be conducted
+according to [the Voting Protocol bylaws](001-voting-protocol.md).
@ghost
ghost added a note

I would like to see some decorum here regarding how a vote is started. I don't like the "broadsides" we've seen. There should be time for final arguments and a date set for the vote to start. So for example you could say now there are 5 days for final arguments and the vote will start on X. That way there would be no surprises and the sponsor of the proposal could be persuaded to cancel the vote if some critical issue was found. We need decorum here or frustration will only increase.

That would fit well here, and I agree that it's needed.

I'm a little worried about specifying an exact time in 3 and 5.1 because we simply don't know how long things should take and what's a reasonable amount of time to wait before making a final decision.

We could just arbitrarily pick a time period and run with it, since this document (if approved) provides a precedent and process for revision, which could be applied to this bylaw once we've got a better idea how long to wait before calling for a vote, or how long to wait between Accepted and Final.

@skyzyx
skyzyx added a note

Agreed. My earlier draft left it unspecified for this same reason. Any input?

@padraic
padraic added a note

Voting dates are at the discretion of whichever voting member is willing to sponsor the proposal. It would be better to define a minimum wait period between proposal date and voting date to prevent any spurious "I published my PR an hour ago - Vote now" misunderstandings.

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

I think 5 days is a little short, maybe 2 weeks? Members could be gone for a week, easily, and miss it.

@skyzyx

I could have sworn that discussion had to be at least 7 days, but I can't find anything in the bylaws, so I guess that doesn't exist. I think that 14 days of discussion allows plenty of time for batting the proposal around, then another 14 days for voting is sufficient.

Yes? No?

@Crell
Collaborator

Voting is 14 days. I think a requirement of at least 14 days of discussion, and at least a 7 day "we're going to be having a vote, dudes!" notice is reasonable.

That does set the absolute minimum time from initial proposal to approval at no less than 4 weeks. If anything I'd say that's too short, but no sense mandating an even longer time. I can't see us doing anything that short anyway.

@Crell
Collaborator

I really like the idea of splitting PSRs into "living documents" and "fixed recommendations". That makes a lot of sense. However, I would recommend differing from IETF in this regard and not using the name namespace for them. That seems like it's asking for confusion when people not in FIG come by and see PSR-8 and go "OMG but these things change!11!!" and we have to explain to them "dude, that's OK, it's an informational PSR" (or the converse). I think having two separate designations (PSR and, uh, something else) will help avoid confusion in the future.

The "Active" vs. "Final" distinction for PSRs makes sense, too. It feels a lot like the "Candidate Recommendation" state for W3C specs. My only concern here is (warning: bikeshed material) if "active" implies "you should use" not "this is in RC draft state".

@eddieajau

During the discussion of the original PSR-1, I mentioned the notion of "Normative" (required, law, binding, tough luck if you don't agree) vs "Informative" (recommended, ignore if desired) (those are terms used by Australia Standards, maybe the ISO's as well) and I'm pretty sure I said we should consider all the code style stuff "Informative". They are a bit jargony but they are hit the nail on the head.

So, rather than having two type of PSR's (active vs final, whatever), just spell out in the text which parts of it are normative and informative is an option that I've seen successfully used.

@eddieajau

Point of order (and mea culpa). Discussion should be only on the mailing list. Here's the thread:
https://groups.google.com/forum/?fromgroups=#!topic/php-fig/uMB4B7uZ7FY

@skyzyx

Agreed. Please funnel further responses into the mailing list.

https://groups.google.com/forum/#!topic/php-fig/uMB4B7uZ7FY

@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((15 lines not shown))
+
+
+## PSR Types
+
+There are two types of PSRs:
+
+ * A _Recommendation Track_ PSR describes a new standard, a common interface,
+ or recommendation for the FIG.
+
+ * An _Informational_ PSR describes a PHP design issue, puts forth a coding
+ standard, describes a best practice, or provides general guidelines to the
+ FIG and PHP community. It does not provide interfaces or concrete
+ implementations. While no PSRs are binding, an Informational PSR does not
+ necessarily represent a FIG consensus or recommendation, so members and users
+ are free to ignore Informational PSRs or follow their advice.
+
@padraic
padraic added a note

There's a lot of crossover between the two definitions. Any way of sharpening each or is the distinction too narrow to be reliably defined?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((21 lines not shown))
+ * A _Recommendation Track_ PSR describes a new standard, a common interface,
+ or recommendation for the FIG.
+
+ * An _Informational_ PSR describes a PHP design issue, puts forth a coding
+ standard, describes a best practice, or provides general guidelines to the
+ FIG and PHP community. It does not provide interfaces or concrete
+ implementations. While no PSRs are binding, an Informational PSR does not
+ necessarily represent a FIG consensus or recommendation, so members and users
+ are free to ignore Informational PSRs or follow their advice.
+
+
+## PSR Workflow
+
+1. To be considered by the FIG, a PSR draft MUST prepared and proposed for
+discussion and review on the php-fig mailing list. The PSR status at this time
+is _Proposed_. Draft authors SHOULD collect community feedback. Depending on the
@padraic
padraic added a note

MUST invite/seek community feedback. It's hardly an optional step while it may appear inevitable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((30 lines not shown))
+
+
+## PSR Workflow
+
+1. To be considered by the FIG, a PSR draft MUST prepared and proposed for
+discussion and review on the php-fig mailing list. The PSR status at this time
+is _Proposed_. Draft authors SHOULD collect community feedback. Depending on the
+proposal, they MAY conduct polls, or compile relevant statistics on current
+implementations and prior art. Drafts SHOULD be discussed, revised, and amended
+according to the feedback recieved.
+
+2. During the discussion phase, the draft proposal MUST be designated as either
+an _Informational_ proposal, or a _Recommendation Track_ proposal.
+
+3. After sufficient discussion has occured, and draft revision is finalized, a
+voting member MAY call for a vote. The voting process MUST then be conducted
@padraic
padraic added a note

Assuming proposed standards can be taken from the floor (i.e. non voting members), we should probably explicitly mention that the sponsorship of a voting member is needed further up the chain just to emphasis that fact (up near where the voting bylaws are linked - folk tend not to slowly read linked material).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((36 lines not shown))
+is _Proposed_. Draft authors SHOULD collect community feedback. Depending on the
+proposal, they MAY conduct polls, or compile relevant statistics on current
+implementations and prior art. Drafts SHOULD be discussed, revised, and amended
+according to the feedback recieved.
+
+2. During the discussion phase, the draft proposal MUST be designated as either
+an _Informational_ proposal, or a _Recommendation Track_ proposal.
+
+3. After sufficient discussion has occured, and draft revision is finalized, a
+voting member MAY call for a vote. The voting process MUST then be conducted
+according to [the Voting Protocol bylaws](001-voting-protocol.md).
+
+4. Once a PSR designated as _Informational_ is passed by a vote, it is assigned
+the _Active_ status, and receives the next available `PSR` identifier.
+
+ 4.1\. A PSR designated as _Informational_ MAY be adapted over time by
@padraic
padraic added a note

Adopted ;)

That was intended to be "adapted". It might be clearer to say "revised".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((40 lines not shown))
+
+2. During the discussion phase, the draft proposal MUST be designated as either
+an _Informational_ proposal, or a _Recommendation Track_ proposal.
+
+3. After sufficient discussion has occured, and draft revision is finalized, a
+voting member MAY call for a vote. The voting process MUST then be conducted
+according to [the Voting Protocol bylaws](001-voting-protocol.md).
+
+4. Once a PSR designated as _Informational_ is passed by a vote, it is assigned
+the _Active_ status, and receives the next available `PSR` identifier.
+
+ 4.1\. A PSR designated as _Informational_ MAY be adapted over time by
+ drafting a new revision, proposing it, and going through the full discussion
+ and voting cycle. The revised PSR MUST maintain the same PSR number, and is
+ considered an up-to-date revision of the PSR. The history of each PSR can be
+ viewed via version control.
@padraic
padraic added a note

This will have potential side effects:
1. The standard is never marked obsolete.
2. Off-site copies will always be obsolete misinformation.
3. It lets lazy researchers off the hook by allowing them to correct misinformation or false advice at some undetermined future date.
4. It may discourage broad rewrites of the standard.

There's a reason why standards revision tends towards uniquely identifying updated standards independently of the obsolete copy.

Active recommendations are intentionally not marked obsolete. The prior art for this is the Informational PEPs (see, PEP 1, PEP 8, etc). Looking through their revision history, most seem to have five or fewer revisions over the last 12 years. Revisions still have to go through the same approval process, so backwards incompatibilities will most likely get shot down anyway.

Informational PSRs are analogous to the Non-standards Track RFCs from the IETF, or to the Informational PEPs. They are things like coding standards and style guides and such, which won't break backwards compatibility if they're updated to stay relevant.

As I see it, our options are to follow the lead of Python / PEP and explicitly define and allow a reasonable scope for change, or to follow the lead of the IETF and adopt a long and rigorous proposal and recommendation and implementation cycle and set them in stone once they're completed.

Before we jump too hastily into the second option, we should remember:

It sometimes takes years to get something approved to even enter the IETF Standards Track.

Once a proposal has been proven useful, and approved by the IESG, it becomes a "Proposed Standard". By this point, there are often several real world implementations. It is "considered well-understood" and has recieved "significant community review".

Per section 6.2 of RFC 2026:

A specification shall remain at the Proposed Standard level for at least six (6) months.

... then it can be considered for promotion to a Draft Standard. A this point it has to have "at least two independent and interoperable implementations from different code bases". Keep in mind that it's still not a standard, but it is considered reasonable for vendors to start deploying implementations "into a disruption sensitive environment." But it's not done yet. The Draft Standard can still be changed to solve problems found in implementation. And it has a waiting period as well:

A specification shall remain at the Draft Standard level for at least four (4) months, or until at least one IETF meeting has occurred, whichever comes later.

... so now we're at 10 months to a year. But it's still not done:

A specification may be (indeed, is likely to be) revised as it advances through the standards track. At each stage, the IESG shall determine the scope and significance of the revision to the specification, and, if necessary and appropriate, modify the recommended action. Minor revisions are expected, but a significant revision may require that the specification accumulate more experience at its current maturity level before progressing. Finally, if the specification has been changed very significantly, the IESG may recommend that the revision be treated as a new document, re-entering the standards track at the beginning.

... so after entering the (minimum) 10-month standards track to go from a proposal to a standard, if the board decides the spec has changed significantly, they may (and often do) recommend that it is treated as a new document and the 10-month clock starts over.

Judging from how things have gone with the four PSRs we've passed so far, the PEP approach seems a lot more pragmatic and reasonable to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((55 lines not shown))
+ viewed via version control.
+
+ 4.2\. An _Informational_ PSR MAY remain in _Active_ status,
+ and SHOULD be adjusted over time to stay relevant. This could be forever, or
+ it could just be until it is deprecated by new PSR.
+
+ 4.3\. A PSR designated as _Informational_ MAY eventually be designated as
+ _Final_, indicating that no future maintenance is expected. This SHOULD
+ happen in the event that a previous Informational PSR is superseded or
+ deprecated by another PSR.
+
+5. When a _Recommendation Track_ PSR completes the proposal process and is
+accepted by vote, it is assigned the _Accepted_ status, and receives the next
+available `PSR` identifier. It is now considered a recommendation of the FIG.
+This status is analogous to a "code freeze". Reference implementations MAY now
+be implemented, and frameworks and libraries SHOULD begin adopting and
@padraic
padraic added a note

MAY begin adopting. Let's strip this of any perceived pressure from FIG on its members to adopt PSRs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((59 lines not shown))
+ it could just be until it is deprecated by new PSR.
+
+ 4.3\. A PSR designated as _Informational_ MAY eventually be designated as
+ _Final_, indicating that no future maintenance is expected. This SHOULD
+ happen in the event that a previous Informational PSR is superseded or
+ deprecated by another PSR.
+
+5. When a _Recommendation Track_ PSR completes the proposal process and is
+accepted by vote, it is assigned the _Accepted_ status, and receives the next
+available `PSR` identifier. It is now considered a recommendation of the FIG.
+This status is analogous to a "code freeze". Reference implementations MAY now
+be implemented, and frameworks and libraries SHOULD begin adopting and
+implementing the recommendation.
+
+ 5.1\. Once a _Recommendation Track_ PSR is designated as _Accepted_, it will
+ be implemented and learned from of over a period of months. In the event
@padraic
padraic added a note

Remove "of"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((61 lines not shown))
+ 4.3\. A PSR designated as _Informational_ MAY eventually be designated as
+ _Final_, indicating that no future maintenance is expected. This SHOULD
+ happen in the event that a previous Informational PSR is superseded or
+ deprecated by another PSR.
+
+5. When a _Recommendation Track_ PSR completes the proposal process and is
+accepted by vote, it is assigned the _Accepted_ status, and receives the next
+available `PSR` identifier. It is now considered a recommendation of the FIG.
+This status is analogous to a "code freeze". Reference implementations MAY now
+be implemented, and frameworks and libraries SHOULD begin adopting and
+implementing the recommendation.
+
+ 5.1\. Once a _Recommendation Track_ PSR is designated as _Accepted_, it will
+ be implemented and learned from of over a period of months. In the event
+ that something unexpected turns up, we MAY reword things for clarity. We MAY
+ adjust actual details, too, if the situation warrants it. But we SHOULD do
@padraic
padraic added a note

MUST? SHOULD smacks of perceived carelessness around backwards compatibility breaks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((66 lines not shown))
+5. When a _Recommendation Track_ PSR completes the proposal process and is
+accepted by vote, it is assigned the _Accepted_ status, and receives the next
+available `PSR` identifier. It is now considered a recommendation of the FIG.
+This status is analogous to a "code freeze". Reference implementations MAY now
+be implemented, and frameworks and libraries SHOULD begin adopting and
+implementing the recommendation.
+
+ 5.1\. Once a _Recommendation Track_ PSR is designated as _Accepted_, it will
+ be implemented and learned from of over a period of months. In the event
+ that something unexpected turns up, we MAY reword things for clarity. We MAY
+ adjust actual details, too, if the situation warrants it. But we SHOULD do
+ them with the same amount of care as we would changing an API after a code
+ freeze. All revisions to an _Accepted_ PSR MUST follow the standard proposal
+ and voting cycle.
+
+ 5.2\. Once the pre-defined period of time has expired, the _Accepted_ PSR
@padraic
padraic added a note

Need to define time if it is to be pre-determined.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((68 lines not shown))
+available `PSR` identifier. It is now considered a recommendation of the FIG.
+This status is analogous to a "code freeze". Reference implementations MAY now
+be implemented, and frameworks and libraries SHOULD begin adopting and
+implementing the recommendation.
+
+ 5.1\. Once a _Recommendation Track_ PSR is designated as _Accepted_, it will
+ be implemented and learned from of over a period of months. In the event
+ that something unexpected turns up, we MAY reword things for clarity. We MAY
+ adjust actual details, too, if the situation warrants it. But we SHOULD do
+ them with the same amount of care as we would changing an API after a code
+ freeze. All revisions to an _Accepted_ PSR MUST follow the standard proposal
+ and voting cycle.
+
+ 5.2\. Once the pre-defined period of time has expired, the _Accepted_ PSR
+ moves into a _Final_ state. In general, _Recommendation Track_ PSRs are no
+ longer maintained after they have reached the _Final_ state. At this point,
@padraic
padraic added a note

maintained vs edited?

Maintained is PEP's language. Maintained, updated or edited should all work... I don't particularly have a preference.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@padraic padraic commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((73 lines not shown))
+ 5.1\. Once a _Recommendation Track_ PSR is designated as _Accepted_, it will
+ be implemented and learned from of over a period of months. In the event
+ that something unexpected turns up, we MAY reword things for clarity. We MAY
+ adjust actual details, too, if the situation warrants it. But we SHOULD do
+ them with the same amount of care as we would changing an API after a code
+ freeze. All revisions to an _Accepted_ PSR MUST follow the standard proposal
+ and voting cycle.
+
+ 5.2\. Once the pre-defined period of time has expired, the _Accepted_ PSR
+ moves into a _Final_ state. In general, _Recommendation Track_ PSRs are no
+ longer maintained after they have reached the _Final_ state. At this point,
+ it's canon. Any further changes SHOULD be proposed and accepted in a
+ superseding PSR, which deprecates this one and replaces it with
+ something new.
+
+6. PSRs which were passed by vote before this bylaw was put into effect SHOULD
@padraic
padraic added a note

Add some blank placeholders where we can insert application dates to avoid any confusion on when this particular requirement enters into the bylaws. Perhaps put those dates into a header section?

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

Please do not comment this PR. Discuss here: https://groups.google.com/forum/#!topic/php-fig/uMB4B7uZ7FY

@padraic

I've posted a summary of other comments to the ML ;).

@philsturgeon philsturgeon commented on the diff
bylaws/003-psr-acceptance-and-revision.md
((10 lines not shown))
+Proposals which are passed according to the [Voting Protocol](001-voting-protocol.md)
+become FIG recommendations. The intention of this bylaw is to provide guidelines
+for the proposal process, as well as addressing revisions to our recommendations
+as the PHP language and our community changes over time. This process is loosely
+based on the Python community's [PEP process](http://www.python.org/dev/peps/pep-0001/).
+
+
+## PSR Types
+
+There are two types of PSRs:
+
+ * A _Recommendation Track_ PSR describes a new standard, a common interface,
+ or recommendation for the FIG.
+
+ * An _Informational_ PSR describes a PHP design issue, puts forth a coding
+ standard, describes a best practice, or provides general guidelines to the
@philsturgeon Owner

This wording makes it sound like we're putting a PHP-FIG logo on phptherightway.com. What is an example of an informational PSR? Why are we providing general guidelines to the PHP community? Why does an Informational PSR not necessarily represent a FIG consensus or recommendation? What is the point of these things at all then?

This wording needs to be drastically improved. I'll have a go at helping, but I dont understand what these are all about.

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

It seems to me that this conversation has given way to a more active discussion:

https://groups.google.com/forum/#!topic/php-fig/YTWBEuDvlwE

Can this be closed so we don't have two similar proposals?

@philsturgeon

Nobody seems to disagree that this conversation has been superseded, so now I can close this im gonna. Feel free to let me know if this is wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 91 additions and 0 deletions.
  1. +91 −0 bylaws/003-psr-acceptance-and-revision.md
View
91 bylaws/003-psr-acceptance-and-revision.md
@@ -0,0 +1,91 @@
+# PSR Acceptance and Revision Guidelines
+
+* **Author(s):** Ryan Parman, Justin Hileman
+* **Status:** Proposed
+* **Initially proposed:** 2013-02-27
+
+
+The PHP Framework Interoperability Group provides recommendations and guidelines
+for FIG member projects specifically, and to the PHP community in general.
+Proposals which are passed according to the [Voting Protocol](001-voting-protocol.md)
+become FIG recommendations. The intention of this bylaw is to provide guidelines
+for the proposal process, as well as addressing revisions to our recommendations
+as the PHP language and our community changes over time. This process is loosely
+based on the Python community's [PEP process](http://www.python.org/dev/peps/pep-0001/).
+
+
+## PSR Types
+
+There are two types of PSRs:
+
+ * A _Recommendation Track_ PSR describes a new standard, a common interface,
+ or recommendation for the FIG.
+
+ * An _Informational_ PSR describes a PHP design issue, puts forth a coding
+ standard, describes a best practice, or provides general guidelines to the
@philsturgeon Owner

This wording makes it sound like we're putting a PHP-FIG logo on phptherightway.com. What is an example of an informational PSR? Why are we providing general guidelines to the PHP community? Why does an Informational PSR not necessarily represent a FIG consensus or recommendation? What is the point of these things at all then?

This wording needs to be drastically improved. I'll have a go at helping, but I dont understand what these are all about.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ FIG and PHP community. It does not provide interfaces or concrete
+ implementations. While no PSRs are binding, an Informational PSR does not
+ necessarily represent a FIG consensus or recommendation, so members and users
+ are free to ignore Informational PSRs or follow their advice.
+
@padraic
padraic added a note

There's a lot of crossover between the two definitions. Any way of sharpening each or is the distinction too narrow to be reliably defined?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+## PSR Workflow
+
+1. To be considered by the FIG, a PSR draft MUST prepared and proposed for
+discussion and review on the php-fig mailing list. The PSR status at this time
+is _Proposed_. Draft authors SHOULD collect community feedback. Depending on the
@padraic
padraic added a note

MUST invite/seek community feedback. It's hardly an optional step while it may appear inevitable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+proposal, they MAY conduct polls, or compile relevant statistics on current
+implementations and prior art. Drafts SHOULD be discussed, revised, and amended
+according to the feedback recieved.
+
+2. During the discussion phase, the draft proposal MUST be designated as either
+an _Informational_ proposal, or a _Recommendation Track_ proposal.
+
+3. After sufficient discussion has occured, and draft revision is finalized, a
+voting member MAY call for a vote. The voting process MUST then be conducted
@padraic
padraic added a note

Assuming proposed standards can be taken from the floor (i.e. non voting members), we should probably explicitly mention that the sponsorship of a voting member is needed further up the chain just to emphasis that fact (up near where the voting bylaws are linked - folk tend not to slowly read linked material).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+according to [the Voting Protocol bylaws](001-voting-protocol.md).
@ghost
ghost added a note

I would like to see some decorum here regarding how a vote is started. I don't like the "broadsides" we've seen. There should be time for final arguments and a date set for the vote to start. So for example you could say now there are 5 days for final arguments and the vote will start on X. That way there would be no surprises and the sponsor of the proposal could be persuaded to cancel the vote if some critical issue was found. We need decorum here or frustration will only increase.

That would fit well here, and I agree that it's needed.

I'm a little worried about specifying an exact time in 3 and 5.1 because we simply don't know how long things should take and what's a reasonable amount of time to wait before making a final decision.

We could just arbitrarily pick a time period and run with it, since this document (if approved) provides a precedent and process for revision, which could be applied to this bylaw once we've got a better idea how long to wait before calling for a vote, or how long to wait between Accepted and Final.

@skyzyx
skyzyx added a note

Agreed. My earlier draft left it unspecified for this same reason. Any input?

@padraic
padraic added a note

Voting dates are at the discretion of whichever voting member is willing to sponsor the proposal. It would be better to define a minimum wait period between proposal date and voting date to prevent any spurious "I published my PR an hour ago - Vote now" misunderstandings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+4. Once a PSR designated as _Informational_ is passed by a vote, it is assigned
+the _Active_ status, and receives the next available `PSR` identifier.
+
+ 4.1\. A PSR designated as _Informational_ MAY be adapted over time by
@padraic
padraic added a note

Adopted ;)

That was intended to be "adapted". It might be clearer to say "revised".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ drafting a new revision, proposing it, and going through the full discussion
+ and voting cycle. The revised PSR MUST maintain the same PSR number, and is
+ considered an up-to-date revision of the PSR. The history of each PSR can be
+ viewed via version control.
@padraic
padraic added a note

This will have potential side effects:
1. The standard is never marked obsolete.
2. Off-site copies will always be obsolete misinformation.
3. It lets lazy researchers off the hook by allowing them to correct misinformation or false advice at some undetermined future date.
4. It may discourage broad rewrites of the standard.

There's a reason why standards revision tends towards uniquely identifying updated standards independently of the obsolete copy.

Active recommendations are intentionally not marked obsolete. The prior art for this is the Informational PEPs (see, PEP 1, PEP 8, etc). Looking through their revision history, most seem to have five or fewer revisions over the last 12 years. Revisions still have to go through the same approval process, so backwards incompatibilities will most likely get shot down anyway.

Informational PSRs are analogous to the Non-standards Track RFCs from the IETF, or to the Informational PEPs. They are things like coding standards and style guides and such, which won't break backwards compatibility if they're updated to stay relevant.

As I see it, our options are to follow the lead of Python / PEP and explicitly define and allow a reasonable scope for change, or to follow the lead of the IETF and adopt a long and rigorous proposal and recommendation and implementation cycle and set them in stone once they're completed.

Before we jump too hastily into the second option, we should remember:

It sometimes takes years to get something approved to even enter the IETF Standards Track.

Once a proposal has been proven useful, and approved by the IESG, it becomes a "Proposed Standard". By this point, there are often several real world implementations. It is "considered well-understood" and has recieved "significant community review".

Per section 6.2 of RFC 2026:

A specification shall remain at the Proposed Standard level for at least six (6) months.

... then it can be considered for promotion to a Draft Standard. A this point it has to have "at least two independent and interoperable implementations from different code bases". Keep in mind that it's still not a standard, but it is considered reasonable for vendors to start deploying implementations "into a disruption sensitive environment." But it's not done yet. The Draft Standard can still be changed to solve problems found in implementation. And it has a waiting period as well:

A specification shall remain at the Draft Standard level for at least four (4) months, or until at least one IETF meeting has occurred, whichever comes later.

... so now we're at 10 months to a year. But it's still not done:

A specification may be (indeed, is likely to be) revised as it advances through the standards track. At each stage, the IESG shall determine the scope and significance of the revision to the specification, and, if necessary and appropriate, modify the recommended action. Minor revisions are expected, but a significant revision may require that the specification accumulate more experience at its current maturity level before progressing. Finally, if the specification has been changed very significantly, the IESG may recommend that the revision be treated as a new document, re-entering the standards track at the beginning.

... so after entering the (minimum) 10-month standards track to go from a proposal to a standard, if the board decides the spec has changed significantly, they may (and often do) recommend that it is treated as a new document and the 10-month clock starts over.

Judging from how things have gone with the four PSRs we've passed so far, the PEP approach seems a lot more pragmatic and reasonable to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+ 4.2\. An _Informational_ PSR MAY remain in _Active_ status,
+ and SHOULD be adjusted over time to stay relevant. This could be forever, or
+ it could just be until it is deprecated by new PSR.
+
+ 4.3\. A PSR designated as _Informational_ MAY eventually be designated as
+ _Final_, indicating that no future maintenance is expected. This SHOULD
+ happen in the event that a previous Informational PSR is superseded or
+ deprecated by another PSR.
+
+5. When a _Recommendation Track_ PSR completes the proposal process and is
+accepted by vote, it is assigned the _Accepted_ status, and receives the next
+available `PSR` identifier. It is now considered a recommendation of the FIG.
+This status is analogous to a "code freeze". Reference implementations MAY now
+be implemented, and frameworks and libraries SHOULD begin adopting and
@padraic
padraic added a note

MAY begin adopting. Let's strip this of any perceived pressure from FIG on its members to adopt PSRs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+implementing the recommendation.
+
+ 5.1\. Once a _Recommendation Track_ PSR is designated as _Accepted_, it will
+ be implemented and learned from of over a period of months. In the event
@padraic
padraic added a note

Remove "of"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ that something unexpected turns up, we MAY reword things for clarity. We MAY
+ adjust actual details, too, if the situation warrants it. But we SHOULD do
@padraic
padraic added a note

MUST? SHOULD smacks of perceived carelessness around backwards compatibility breaks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ them with the same amount of care as we would changing an API after a code
+ freeze. All revisions to an _Accepted_ PSR MUST follow the standard proposal
+ and voting cycle.
+
+ 5.2\. Once the pre-defined period of time has expired, the _Accepted_ PSR
@padraic
padraic added a note

Need to define time if it is to be pre-determined.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ moves into a _Final_ state. In general, _Recommendation Track_ PSRs are no
+ longer maintained after they have reached the _Final_ state. At this point,
@padraic
padraic added a note

maintained vs edited?

Maintained is PEP's language. Maintained, updated or edited should all work... I don't particularly have a preference.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ it's canon. Any further changes SHOULD be proposed and accepted in a
+ superseding PSR, which deprecates this one and replaces it with
+ something new.
+
+6. PSRs which were passed by vote before this bylaw was put into effect SHOULD
@padraic
padraic added a note

Add some blank placeholders where we can insert application dates to avoid any confusion on when this particular requirement enters into the bylaws. Perhaps put those dates into a header section?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+adopt an _Informational_ or _Recommendation Track_ designation by through the
+standard proposal and voting process. Future changes SHOULD be made as outlined
+in this bylaw.
Something went wrong with that request. Please try again.