Proposed bylaw addressing how to version/supersede existing PSRs

[Ryan Parman]

https://github.com/php-fig/fig-standards/pull/93/files

This is my attempt at drafting a bylaw to address how we handle updates, versions, and replacements of existing PSRs.

It was born to address some of the questions around the proposed vote to "adjust" PSR-2, but also think about the future of the group's work.

--

Ryan Parman

Geek. Writer. Music Lover.

http://ryanparman.com

"Illiteracy will not be defined by those who cannot read and write, but by those who cannot learn and relearn." — Alvin Toffler

[Andrew Eddie]

That's a good start. I've added my thoughts.

Regards,

Andrew Eddie

[Ryan Parman]

Short version: I like Justin Hileman'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.

Thanks! :)

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/ar8Nnt6lGbMJ.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Lukas Kahwe Smith]

On Feb 28, 2013, at 7:20 , Ryan Parman <ry...@ryanparman.com> wrote:

> Short version: I like Justin Hileman'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.

I liked the previous version better. I am not sure if this "Current best practice" buys us anything but continued discussions. I also do not think that its very useful to point people at version history to find out what a standard was. I mean if I specify that I am following PSR-4 and suddenly PSR-4 changes then I am in violation of a standard I was previously compliant with and suddenly I feel forced to either remove the reference or change my code. I much prefer us to just create a new PSR and then people can choose to adopt this new version on their own time.

regards,
Lukas Kahwe Smith
sm...@pooteeweet.org

[Ryan Parman]

On Feb 28, 2013, at 12:22 AM, Lukas Kahwe Smith <sm...@pooteeweet.org> wrote:

> [...] then I am in violation of a standard I was previously compliant with and suddenly I feel forced to either remove the reference or change my code.

This is not how the FIG works, and is proving to be a fundamental misunderstanding of this group.

We don't make standards. There are no violations. There is no compliance. We recommend patterns that improve interoperability with like-minded software projects.

This bylaw would allow us to adapt and make adjustments over time as the group votes necessary, which I think is a good idea.

Hopefully, we won't have any more style-related proposals and can focus on more important things. If the PHP Core team were to add native support for auto-loading classes that was different from PSR-0, surely we'd want to have the option of adapting our recommendation.

I would suggest that PSR-0 be about the best practice for auto-loading classes, not just this one specific way of autoloading. Likewise, I would suggest that PSR-3 be about the best practice for logging, not just this one specific way of logging.

This bylaw doesn't force that issue, but it does open the door for the group to consider it in the future.

[Lukas Smith]

On Feb 28, 2013, at 16:45 , Ryan Parman <ry...@ryanparman.com> wrote:

> On Feb 28, 2013, at 12:22 AM, Lukas Kahwe Smith <sm...@pooteeweet.org> wrote:
>
>> [...] then I am in violation of a standard I was previously compliant with and suddenly I feel forced to either remove the reference or change my code.
>
> This is not how the FIG works, and is proving to be a fundamental misunderstanding of this group.
>
> We don't make standards. There are no violations. There is no compliance. We recommend patterns that improve interoperability with like-minded software projects.

you can be non compliant with a recommendation. at any rate .. if i link to something to say "we are using this to format our code" or "we are using this interface" and then someone changes this .. then i either have to change my code or remove the reference. actually in the case of an interface that changes i will end up with fatal errors potentially (yes i assume in this case we would use composer or something so someone could reference a specific version but this then means we suddenly do have versioning).

regards,
Lukas

[Drak]

On 28 February 2013 15:45, Ryan Parman <ry...@ryanparman.com> wrote:

On Feb 28, 2013, at 12:22 AM, Lukas Kahwe Smith <sm...@pooteeweet.org> wrote:

> [...] then I am in violation of a standard I was previously compliant with and suddenly I feel forced to either remove the reference or change my code.

This is not how the FIG works, and is proving to be a fundamental misunderstanding of this group.

We don't make standards. There are no violations. There is no compliance. We recommend patterns that improve interoperability with like-minded software projects.

Lukas says, you could not change it so that PSR-X means one thing today, and another tomorrow. - that would be chaos.

Regards,

Drak

[Ryan Parman]

That would be a somewhat extremist way to look at it. I do not believe that the voting members would pass a revision that was such a radical departure.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

[Anthony Ferrara]

Ryan

On Thu, Feb 28, 2013 at 11:40 AM, Ryan Parman <ry...@ryanparman.com> wrote:

That would be a somewhat extremist way to look at it. I do not believe that the voting members would pass a revision that was such a radical departure.

The point is that *any* departure is a radical departure... Any change after acceptance only causes people pain. It helps nobody.

Whereas if you extend or supersede with a new PSR, the old remains just as valid and works, and the new remains useful. The best of both worlds...

[Drak]

Well said Anthony.

--

[Johannes Schmitt]

I think there are cases where a revision would be useful:

- a typo is found in the text
- the text is too unclear and/or ambiguous

Of course, it's a fine line to walk, and there should be very strict requirements for those revisions to be accepted.

Cheers,
Johannes

[Drak]

If such a thing were to occur, it would be a very very telling sign we are not spending enough time in the discussion and review phase. Can you imagine the IETF making such typos? I think there should be no room for mistake - maybe that's why standards bodies take such a long time to do anything....? 

Regards,

Drak

[Anthony Ferrara]

Johannes,

I think there are cases where a revision would be useful:

- a typo is found in the text
- the text is too unclear and/or ambiguous

Of course, it's a fine line to walk, and there should be very strict requirements for those revisions to be accepted.

I agree with Drak that it would be troubling if such a standard got through to acceptance with those issues.

With that said, if you check out RFC2026, there are variance procedures (section 9). Basically where it can be allowed to vary the written procedure as necessary...

What is telling, is that the first sentence of section 6.3 is explicitly disallowed to be varied:

6.3  Revising a Standard

   A new version of an established Internet Standard must progress
   through the full Internet standardization process as if it were a
   completely new specification.  

Which means that it must get a new number and proceed as a new spec with everything associated with it.

The thought process here is that there's no such thing as a small change. Even a typo can be considered a large change. And if text is ambiguous or unclear, that should be identified in the process, and if not, remains unclear for all time, until a new standard comes out to rectify it. As I said before, I think *any* change is a big one to an accepted standard (RFC)...

[Lukas Kahwe Smith]

well there is the famous "referer" typo which was never fixed.

Drak <dr...@zikula.org> wrote:

If such a thing were to occur, it would be a very very telling sign we are not spending enough time in the discussion and review phase. Can you imagine the IETF making such typos? I think there should be no room for mistake - maybe that's why standards bodies take such a long time to do anything....? 

Regards,

Drak

On 28 February 2013 17:02, Johannes Schmitt <schmi...@gmail.com> wrote:

I think there are cases where a revision would be useful:

- a typo is found in the text
- the text is too unclear and/or ambiguous

Of course, it's a fine line to walk, and there should be very strict requirements for those revisions to be accepted.

[justin]

While I agree with the sentiment here, we have not shown the forethought or the attention to detail and process necessary to make "write once" standards. Every time we introduce more process or ask for more time (e.g. more than 10 minutes between proposing a change and calling for a vote) there is push back.

We simply don't take the time that the IETF and other standards bodies take to revise and approve their RFCs.

And I don't think that's a bad thing.

But I also don't think we should take the same hardline approach to changes if we're not willing to put the time and energy into making sure they're solid before approving them.

I think we'd be better off modeling our process after the PEP process. It's a little more lenient in application, and allows limited changes to some documents, and continuous change to others. But documents which will be changed to keep up with current practices or community evolution must be designated as such, and changes must go through the same process as the initial proposal.

The proposal in https://github.com/php-fig/fig-standards/pull/93 attempts to add the minimal amount of process while still accomplishing this goal.

If you haven't recently, read that for some background on my next couple of comments :)

If I were to take a shot at classifying our current PSRs, I would say that *most* are Recommendation Track. Meaning, most would only be changed for clarification of wording or typos or formatting.

PSR-0 — Recommendation Track. It proposes an interface, and thus should not be changed. It has also passed a reasonable period of time, and has been implemented by almost everyone, so the current status would be Final.

PSR-1 — Recommendation Track. This is the minimal set of interoperability "code style" recommendations we could extract from the original coding standard proposal. The current status of PSR-1 would be Accepted.

At this point, minimal "clarity" and "typo" type changes could be made if turned up while implementing this recommendation. Notably, there are some parts which were ambiguous enough to warrant discussion while the PHPCS sniffs were being made. These things should be clarified, as the implementation process inevitably turns up additional questions and inconsistencies.

Note that this period is not intended to change interfaces, or to create a moving target. It should be approached with the same care as changing a public API after code freeze. Only fatal flaws or changes which maintain the intended meaning and compatibility should be accepted.

Also, changes would have to go through the same acceptance process as the initial proposal, which would cut down on inconsequential revisions. Additionally, it would provide an opportunity for those affected by the changes to put their foot down and keep the target from moving :)

PSR-2 — Informational. As outlined in the proposed bylaws, this does not necessarily represent a consensus or even an interoperability requirement, so much as a good reference document and a baseline for conversation.

Additionally, if deemed appropriate, the status on this one could be marked Active. This means we anticipate this Informational PSR to be updated to stay relevant to the community. See PEP 1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 20, 101, 257, etc for examples of Active PEPs. Note that most of these are style guides, processes, or informational. Especially relevant are PEP 8 (their equivalent to PSR-2) and PEP 257 (their equivalent to the docblock standards which have been discussed off and on). Both of these are marked Active, meaning they can and will change to stay relevant.

Note the number of changes though. PEP 257 was created in May 2001, and the last material change was "Added "Handling Docstring Indentation" section" in November 2002. It's hardly a rapidly changing document. Changing PEP 257 rather than creating a new docstring formatting standard makes sense, as having two versions co-exist as "the right way" doesn't really work.

-- justin

[justin]

On Thu, Feb 28, 2013 at 10:10 AM, justin <jus...@justinhileman.info> wrote:

If I were to take a shot at classifying our current PSRs, I would say that *most* are Recommendation Track. Meaning, most would only be changed for clarification of wording or typos or formatting.

Oops. Forgot PSR-3 :)

PSR-3 — Recommendation Track. Again, this recommendation contains interfaces and APIs, so changes shouldn't be considered lightly. The current status would be Accepted. It's pretty much a burn-in phase. Any changes from here on out should be for clarifying issues that come up during implementation by frameworks and libraries, or formatting, or things of similar magnitude. Again, they'd have to follow the same proposal process as a new PSR, they'd just be able to help revise this one so long as they didn't change the intent or the API.

After some number of months, this recommendation would move to Final. This signals that we're done with it, and won't be maintaining it or updating it. Small or large changes will all have to come in the form of a new superseding PSR. Hopefully, though, the burn-in period will be enough to iron out all the small details and only leave us needing to supersede it with newer, awesomer PSRs.

--justin

[Ryan Parman]

Precisely. We need to be taking the long view on this stuff.

Secondly, there is no existing rule on the books that says that PSRs are either revisable or non-revisable. It hasn't been established yet.

I don't support "casual" updates (neither does Justin), but I think that allowing for improvement over time is a forward-thinking approach.

[Anthony Ferrara]

Ryan,

Precisely. We need to be taking the long view on this stuff.

Secondly, there is no existing rule on the books that says that PSRs are either revisable or non-revisable. It hasn't been established yet.

I don't support "casual" updates (neither does Justin), but I think that allowing for improvement over time is a forward-thinking approach.

Pedantic point here: it's a forward-thinking approach for the standards body.

A forward thinking approach for implementers (people in the field) favors rigidity. 

The referer issue pointed at above is a PERFECT example. The rigidity of the RFC means that it's a PITA to change it going forward. 

However, for implementers, saying you're compliant with 2616 means that you're expecting the mis-spelling. It leaves the situation level. And for all time going forward, all 2616 compliant tools will expect that. And if another RFC comes out and "fixes" that error, then you could be compliant with 2616 AND the new version (supporting both), or just the new version. But it's up to the implementer to figure that out.

But if they updated 2616 to fix that spelling error, then all of a sudden everything that *was* 2616 compliant would no longer be. And you'd have a boat load of working interoperable code breaking for no reason. That's why we have protocol identifiers that include version numbers. That's why we have handshakes. So that interoperability is improved.

After all, isn't that what this group is all about?

[justin]

On Thu, Feb 28, 2013 at 10:30 AM, Ryan Parman <ry...@ryanparman.com> wrote:

Precisely. We need to be taking the long view on this stuff.

An analogy regarding the scope of revisions.

If a PSR were under SemVer:

 * an Active status means we're free to change the major version.

 * an Accepted status means we're free to change the minor or patch version (no BC breaks).

 * a Final version means (1) we don't anticipate making *any* changes, and (2) if we do change, it should only be a patch version change.

--justin

[Ryan McCue]

Drak wrote:
> If such a thing were to occur, it would be a very very telling sign we
> are not spending enough time in the discussion and review phase. Can you
> imagine the IETF making such typos? I think there should be no room for
> mistake - maybe that's why standards bodies take such a long time to do
> anything....?

Actually, the IETF makes small mistakes all the time (typos/etc), which
is why RFCs have an errata section if needed.

For example, RFC 2616 [0] (better known as HTTP/1.1) has quite a bit of
errata. [1] HTTP is the basis of most of the web, so if they can't get
it right the first time, I don't think we have much hope.

Also take a look at their errata status codes [2], which include the
"Held for Document Update" status, which allows major problems to be
noted to be corrected in future versions of the spec.

I know the RSS Board (which Ryan is a member of) uses a policy where
minor updates are allowed, but recorded in the history. We could use
this for an errata-style system with Git, but I'd warn against that;
reading a spec one day and seeing it changed the next is very
disconcerting and doesn't fill me with confidence as an implementor.

[0]: http://tools.ietf.org/html/rfc2616
[1]: http://www.rfc-editor.org/errata_search.php?rfc=2616
[2]: http://www.rfc-editor.org/status_type_desc.html

--
Ryan McCue
<http://ryanmccue.info/>

[Ryan Parman]

On Feb 28, 2013, at 5:49 PM, Ryan McCue <li...@rotorised.com> wrote:

> reading a spec one day and seeing it changed the next is very
> disconcerting and doesn't fill me with confidence as an implementor.

Well, to be fair, a 14-day voting period on all changes is, IMO, a bit hard to miss.

Additionally, what are your thoughts on the split model that HTML5 has? WHATWG maintains a living standard, while the W3C chooses to fork versioned snapshots.

Justin and I are proposing a model more like the WHATWG, while Drak, Anthony and Lukas seem to favor the W3C-ish process.

Is this accurate?

I'd be willing to acquiesce on the point of allowing occasional ratified updates to the spec (save for clarity and grammatical changes), provided that the stipulation remains that existing PSRs can be deprecated by newly-ratified PSRs. I expect that a PSR ratified 5 or 10 years ago would look very different from what we're passing now. I expect that the PSRs of 2015 will look different as well.

IMO, we need to ensure we're allowing for growth over time. Might this be the right balance of rigidity and flexibility?

[Larry Garfield]

In other groups I've been in where we've been pedantic about such
changes, we've settled on the term "non-substantive" for the types of
changes that are allowed by an editor. That would include spelling
mistakes (obviously not counting those in interface names and such),
punctuation in a sentence, formatting, etc. Since we have Git available
to us I'm fine with allowing non-substantive changes to an existing PR.
E.g., if someone spotted a "teh" instead of "the" in the PSR-3 spec, bad
on us for not catching it but it's fine to fix in-place.

Substantive changes are... anything else. If we decided that it really
made sense to add a new "zOMG this is bad!" error level to PSR-3, for
instance, that's a substantive change. The way to do that isn't PSR-3
version 2, but a PSR-4 that is very short and says "This PSR extends
PSR-3 to include a zOMG status, with constant value 12". (Or something
like that.) Then projects using PSR-3 can ignore it entirely and keep
working, and those that need a zOMG status can use PSR-4 and not have to
try and figure out what other subtle changes there might be.

PSR-4 then is a subclass of PSR-3. (Sorry, Anthony. <g>)

--Larry Garfield

[Andreas Möller]

> But if they updated 2616 to fix that spelling error, then all of a sudden everything that *was* 2616 compliant would no longer be. And you'd have a boat load of working interoperable code breaking for no reason. That's why we have protocol identifiers that include version numbers. That's why we have handshakes. So that interoperability is improved.
>
> After all, isn't that what this group is all about?

Very good point, Anthony.


No amendments, but revisions with different identifiers. Hey, it's like tagging in version control systems.

Everyone does use a version control system when coding, right?


Best regards,

Andreas

[Andreas Möller]

> IMO, we need to ensure we're allowing for growth over time. Might this be the right balance of rigidity and flexibility?

The group's recommendations can grow and stay rigid at the same time when recommendations are not amended and updated, but a new revision is compiled using the same process - without making a former recommendation invalid (or non-existent, as it has changed and is not the same anymore).

I guess everyone can live with that. E.g., PSR-2:2013, or whatever.


Best,

Andreas

[Andreas Möller]

> PSR-4 then is a subclass of PSR-3. (Sorry, Anthony. <g>)

Personally, I believe a naming or versioning scheme similar to how DIN does it, or semver would be nice. It would be easier to see what recommendation one is talking about (same major version, different minor, maybe).

Regardless of the scheme, I have to agree with Larry concerning the idea of substantial vs. non-substantial changes.

Nonetheless, as has been pointed out before, the highest effort should be put into the process to avoid spelling mistakes and wording issues, to keep the amount of non-substantial changes after a recommendation has been accepted to a minimum.


Best,

Andreas

[Andrew Eddie]

I don't know about anyone else, but I'm getting a bit lost in having discussion here and in the PR (and it feels like in ten other places). Where are we discussing the PR - here or on Github?

Regards,
Andrew Eddie

[Paul Dragoonis]

On Fri, Mar 1, 2013 at 8:01 AM, Andrew Eddie <mamb...@gmail.com> wrote:

I don't know about anyone else, but I'm getting a bit lost in having discussion here and in the PR (and it feels like in ten other places). Where are we discussing the PR - here or on Github?

To partially answer you Andrew, all discussions should be on the mailing list, github is just for making PR's

 

Regards,
Andrew Eddie

[Ryan McCue]

Ryan Parman wrote:
> Well, to be fair, a 14-day voting period on all changes is, IMO, a bit hard to miss.

As long as that's enforced on all changes, I'd be OK with that.

> Additionally, what are your thoughts on the split model that HTML5 has? WHATWG maintains a living standard, while the W3C chooses to fork versioned snapshots.

I don't think that really fits with the FIG model. If we're releasing
interfaces/etc (and the current poll seems to indicate that's the
favoured direction)., then those need to be backwards- and
forwards-compatible. This is unlike HTML, where we're talking about
parsing documents in the wild.

(I'm probably not explaining myself well here, but I like the WHATWG's
direction for formats, but I think W3C-ish works better for APIs/ABIs.)

>
> Justin and I are proposing a model more like the WHATWG, while Drak, Anthony and Lukas seem to favor the W3C-ish process.
>
> Is this accurate?
>
> I'd be willing to acquiesce on the point of allowing occasional ratified updates to the spec (save for clarity and grammatical changes), provided that the stipulation remains that existing PSRs can be deprecated by newly-ratified PSRs. I expect that a PSR ratified 5 or 10 years ago would look very different from what we're passing now. I expect that the PSRs of 2015 will look different as well.

Absolutely, I think the deprecation/superseding of previous standards is
important *regardless of which approach is used*. Standards will
occasionally need to be recreated from scratch; for example, if it turns
out that a previous standard has too little/too much abstraction, that
should be corrected in a V2 (which should be a separate document).

[Andrew Eddie]

Ok, for those that have just joined, we are talking about this file:

https://github.com/skyzyx/fig-standards/blob/810599a649eea99393fc93dab6aea57445cc8142/bylaws/003-psr-acceptance-and-revision.md

> There are two types of PSRs:

Agree 100%. However I want to push that we use terminology used by ISO (International Organisation for Standardisation). See http://en.wikipedia.org/wiki/Normative under the heading of "Standards documents". In particular:

• Normative = prescriptive = how to comply
• Informative = descriptive = help with conceptual understanding

At the end of the day, I don't really mind what the two flavours are called, but as outlined below I think it is critical to mention that one type affects interoperability and the other doesn't.

> A Recommendation Track PSR ...

A "Normative" PSR describes a standard that affects the interoperability of code such as common interfaces, autoloading or how code can brought together from multiple sources without generating errors. Compliance is optional, but it is the only way to guarantee interoperability is achieved within the scope of the PSR.

[In other words, it's like the GPL. You don't have to accept it, but accepting it is the only way you get the rights is affords you.]

> An Informational PSR describes

An "Informative" PSR describes a standard that does not affect the interoperability of code such a standards for code style, API documentation and comments. Compliance is optional.

[I think that's all we need to say]

> 1. To be considered by the FIG ...

I think it's important to add than anyone can propose a PSR.

I also recommend we specify that a proposed PSR can take any form (Gist, Google Doc, fork, whatever) but MUST NOT be a Pull Request on the FIG repo. A PR can only be made after a vote is passed. That will solve this problem of people just making PR's willy nilly and wasting our time.

> During the discussion phase , the draft proposal MUST be designated 

> as either an Informational proposal, or a Recommendation Track proposal.

Per comments above, I'd prefer "Normative" and "Informative". But it's not a hill I'm willing to die on - I agree with the spirit of the separation.

> 3. After sufficient discussion has >occurred< (typo)

I think we should set a minimum of 7 days. We don't want votes going up without discussion if for no other reason than to fix typo's. It doesn't have to be long, it just has to be more than "zero".

I also like the idea that two voting members must "agree" to put a discussion to a vote. It would be some like "Paul moves to vote on this discussion. Seconded by Andrew. Let's vote". But that might be adding unnecessary complexity.

> 4. and 5.

This is the one section I have a problem with. I think it's overly complex in light of all the discussion we'd had to date.

I don't think any of this is necessary to have separate processes - it's double handling. It's either an interoperability issue and combining your code physically breaks something, or it's not an interoperability issue and it is something you can safely ignore if you want.

In terms of changes, I agree that a PSR is "fixed" for all intensive purposes, but we can change an existing PSR, by vote, to:

a) Fix typos.

b) To add an Errata (kudos to whomever first suggested it).

That keeps it simple to explain and simple to enact and any change is by vote anyway. One rule for all PSR's, it's just the designation that affects how people use or perceive them.

So I would roll 4 and 5 into one item like this:

==================

Once a PSR is passed by a vote, it is assigned the the next available PSR identifier. A PSR cannot be changed except by vote and only in the following circumstances:

a) To fix typographical errors that do not change the intent, meaning or interoperability of the PSR, and/or

b) To add an "Errata" that brings to light new information that was not or could not have been considered when the PSR was accepted.

==================

That's easy to read and easy to understand (KISS). The only thing simpler would be to say "no change at all" and I'd also support that but I wouldn't prefer it.

So for example, PSR-2 could have an errata for some new language construct in PHP 5.7, but to cover comments and DocBlocks, you need a new PSR. I would not add an errata to PSR-2 to deal with variation of style (tabs, braces, whatever), but I would, per the last point in the proposal, vote to make it "informational" or whatever we call it.

Likewise, PSR-0 could add an errata for some problematic issue that arises between PHP 5.4 and 5.5 that was unknown or unforeseen when it was adopted. But a completely new way of autoloading would need to be a new PSR (PSR-0 is useful up to PHP 5.8, but for PHP 6.0 we need a new PSR because things have changed too much).

Errata's could also be used to provide guidance for future PSR's. For example, we might need to add a note to PSR-0 on how to handle a special case brought up by a hitherto unknown PSR-8.

Errata's could not, however, introduce backward incompatible interpretation (to Anthony's point above). You can't create a paradox.

I don't think we need to get carried away with what an errata is or isn't - if we all agree by vote that it's suitable, what does it matter.

The only other thing from previous conversations is whether we should handle the case of "superseded". I'm inclined to ignore that for now and cross that bridge if we ever come to it.

> 6.

I'm ok with this but I'd like the voting members to commit to actually doing this for all of them. It's only four separate votes.

I think it's worth adding an "Example" section to the end of the bylaw just to walk people through the whole process, and also help make sure we are all on the same page. Thoughts?

Regards,

Andrew Eddie

[justin]

On Fri, Mar 1, 2013 at 4:41 PM, Andrew Eddie <mamb...@gmail.com> wrote:

Ok, for those that have just joined, we are talking about this file:

https://github.com/skyzyx/fig-standards/blob/810599a649eea99393fc93dab6aea57445cc8142/bylaws/003-psr-acceptance-and-revision.md

Cross-posting from the PR comments:

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. 

[Mike van Riel]

On Saturday, 2 March 2013 01:41:17 UTC+1, Andrew Eddie wrote:

Ok, for those that have just joined, we are talking about this file:

https://github.com/skyzyx/fig-standards/blob/810599a649eea99393fc93dab6aea57445cc8142/bylaws/003-psr-acceptance-and-revision.md

> There are two types of PSRs:

Agree 100%. However I want to push that we use terminology used by ISO (International Organisation for Standardisation). See http://en.wikipedia.org/wiki/Normative under the heading of "Standards documents". In particular:

• Normative = prescriptive = how to comply
• Informative = descriptive = help with conceptual understanding

At the end of the day, I don't really mind what the two flavours are called, but as outlined below I think it is critical to mention that one type affects interoperability and the other doesn't.

I would prefer if the difference between these two tracks is described in more detail. The current description is open to interpretation and hence debate.

Allow me to explain with an example that is very personal to me, the PHPDoc Standard and the use of DocBlocks.

To me, the PHPDoc Standard (description of the Syntax, which tags exist, which structures there are, ABNF and all) would be a recommendation on the Normative track. Although it isn't code that is being described it does however prescribe syntax that helps interoperability between projects (how can an IDE or  documentation generator do its work if the recommendation is not followed?).

I would however consider the recommendation describing which DocBlocks and tags are required, or recommended, in a project to be an informative track. What a project requires in terms of source documentation is something that is to be considered a coding standard and often very personal.

[Andrew Eddie]

On 2 March 2013 17:17, Mike van Riel <draco...@gmail.com> wrote:

Allow me to explain with an example that is very personal to me, the PHPDoc Standard and the use of DocBlocks.

To me, the PHPDoc Standard (description of the Syntax, which tags exist, which structures there are, ABNF and all) would be a recommendation on the Normative track. Although it isn't code that is being described it does however prescribe syntax that helps interoperability between projects (how can an IDE or  documentation generator do its work if the recommendation is not followed?).

Yes, exactly. Essentially you are defining the "schema". This would be a PSR-3 "class" of document.

 

I would however consider the recommendation describing which DocBlocks and tags are required, or recommended, in a project to be an informative track. What a project requires in terms of source documentation is something that is to be considered a coding standard and often very personal.

Yes. This one would tell you which parts of the "schema" are the minimum best practice and we'd do another commonality exercise to determine it. This would be a PSR-2 "class" of document.

That's exactly how I picture it working.

Regards,

Andrew Eddie

[justin]

Agreed. 

You could go a step further than "minimum best practice" in the second document, and produce recommendations. That's the prerogative of a PSR-2-type document (Informational?). Because it doesn't represent a strict standard, or an all-or-nothing implementation, it can provide a few more more SHOULDs and MAYs, while the PSR-3-type documents are mostly MUSTs and SHALLs.

--justin

[Andrew Eddie]

On 2 March 2013 18:41, justin <jus...@justinhileman.info> wrote:

Agreed. 

You could go a step further than "minimum best practice"

Poor choice of phrase, sorry.

 

in the second document, and produce recommendations. That's the prerogative of a PSR-2-type document (Informational?).

Yes. Well, I think it [PSR-2] would be informational - we'll have to wait for the vote to see if that's the majority view.

 

Because it doesn't represent a strict standard, or an all-or-nothing implementation, it can provide a few more more SHOULDs and MAYs, while the PSR-3-type documents are mostly MUSTs and SHALLs.

I think that's a reasonable way to approach it on balance (knowing the devil is in the detail of each case).

Regards,

Andrew Eddie

[Grégoire Bélorgey]

Hi everyone,

I'm quite sorry to jump in like this, given all the noise this group has been through the last few days, but I'd like to add one thing about PSR-2.

Yes. Well, I think it [PSR-2] would be informational - we'll have to wait for the vote to see if that's the majority view.

 

Because it doesn't represent a strict standard, or an all-or-nothing implementation, it can provide a few more more SHOULDs and MAYs, while the PSR-3-type documents are mostly MUSTs and SHALLs.

Although I agree it's neither a strict standard nor an all-or-nothing implementation, it's worth pointing out (as MVOP did in his blog post) that SHOULD and MAY are not easily implemented in a code sniffer. Point is, anyone is free to follow PSR-2 (and any other future informational PSR) or not, but please, for the sake of those following it and using automated scripts to enforce it to their dev teams, don't go too soft and overusing SHOULDs and MAYs.

Overall, a recommandation only made of SHOULDs and MAYs would benefit no one : those in favor would have a hard time enforcing it, and those against would simply not care, just as they would for MUSTs.

Just my 2 cents of course, and not at all opposing your statement, but since we heard a lot about people who don't implement/enforce PSR-2, I'd like to bring some perspective on this ;)

Oh, and please forgive my poor english !

Regards,

Grégoire Bélorgey - Independant developper, mostly aligned with litihum.

[Andrew Eddie]

On 2 March 2013 19:09, Grégoire Bélorgey <g...@mybbservices.com> wrote:

Although I agree it's neither a strict standard nor an all-or-nothing implementation, it's worth pointing out (as MVOP did in his blog post) that SHOULD and MAY are not easily implemented in a code sniffer.

RFC 2119 does allow for you to modify the "force" of the terms. So, it's possible you could say that a MUST in a normative standard is stronger than a MUST in an informative standard. That's probably a recipe for further confusion though. It will really depend on the goal of the document and that's going to come out in any discussion. I would not want to codify the usage of MUST and SHOULD anyway.

 

Overall, a recommandation only made of SHOULDs and MAYs would benefit no one : those in favor would have a hard time enforcing it, and those against would simply not care, just as they would for MUSTs.

I think it's only a problem for Greg to work out what the default settings will be when he ships a new PSR in PHP Code Sniffer (or similar). But after that, any project is probably going to customise the standard anyway. So while two projects may be PSR-N compliant "technically" as a lowest common denominator, each is more likely going to be PSR-N+, where "+" varies from project to project. It's really up to the project to enforce their own take on standards anyway. It's not FIG's job to enforce them.

 

Just my 2 cents of course, and not at all opposing your statement, but since we heard a lot about people who don't implement/enforce PSR-2, I'd like to bring some perspective on this ;)

Oh, and please forgive my poor english !

It's pretty good :)

Regards,

Andrew Eddie 

[Grégoire Bélorgey]

Overall, a recommandation only made of SHOULDs and MAYs would benefit no one : those in favor would have a hard time enforcing it, and those against would simply not care, just as they would for MUSTs.

I think it's only a problem for Greg to work out what the default settings will be when he ships a new PSR in PHP Code Sniffer (or similar). But after that, any project is probably going to customise the standard anyway. So while two projects may be PSR-N compliant "technically" as a lowest common denominator, each is more likely going to be PSR-N+, where "+" varies from project to project. It's really up to the project to enforce their own take on standards anyway. It's not FIG's job to enforce them.

Agreed, but the easier it is to implement/enforce, the better adoption (and interoperability) will be, imho. I really don't think the whole tabs/spaces debate and dicatorship accusations should encourage FIG to take a softer terms policy. The reommandations' "MUST" is only ever as compelling as implementers let them be anyway, but being quite rigid in the PSR is what keeps the lowest common denominator high enough to be usefull.

But i'm drifitng away from the original topic :)

Oh, and please forgive my poor english !

It's pretty good :)

Thanks !

Regards,

Grégoire Bélorgey

[Pádraic Brady]

Hi all,

I have a number of concerns/suggestions about what is being proposed here.

1. The definitions of the two categories in the proposal are far too
ambiguous. We need a clear definition of what is and what is not
subject to substantial changes. I'd also go with Larry's definition of
"substantive and non-substantive changes" as to what triggers the
process for revising a standard and to what degree it is allowed. What
are the key differences between a recommendation and an informational?
Maybe someone could do up a nice matrix showing all the possible
options and permutations?

2. We need to recognise that our limited resources and time will
encourage a higher error rate. Whatever is decided must allow for
non-substantial changes to existing standards for typos, grammar,
obvious errors and the clarification of ambiguous phrases without
releasing a new standard number or significant version.

3. I firmly do not believe that a coding standard is "informational".
You cannot simply take PSR1, change a few bits, and keep calling it
PSR1. You CHANGED something substantial. The next release of a CS
checking tool may completely nuke all legacy code written to the
original standard. In my shoes, that would involve me going to my
office, closing the door, and pretending PSR1 doesn't exist for the
rest of time. If that door is opened, we lose the rigidity of a
standard and the utility of conforming to it. If said CS tool were to
release a separate checking extension for some other standard, at
least I can keep using the old one for legacy code and switch on the
next new project to the new one. It's worth paying attention to the
realities of how PHP projects actually enforce these coding styles.

4. The minimum period between a proposal's publish date and the voting
date must be sufficient to ensure all voting members have had the
opportunity to review and offer feedback. That means >2 weeks. I would
suggest three weeks to include a minimum one week voting notice
separately published to the mailing list (not buried in a 45 email
thread). Passing a standard while a voting member is on vacation is
probably not a good idea. A voting member should be able to defer
voting by notifying FIG if they are unavailable for a period not
exceeding, for example, two weeks.

5. If we allow standards that can be incrementally improved (e.g. they
must out of necessity incorporate accumulated knowledge, data or
evolving best practices) without having their PSR integer incremented,
I'd suggest incorporating a date element into the official title and
making the date obvious in the very first paragraph. This would allow,
for example, PSR7 (2013) and PSR7 (2015) - you can see how that makes
it clear which one is obsolete compared to semver.

6. We need a process to grade standards as obsolete or deprecated in
the absence of an immediate replacement where such a replacement is
obviously required to ensure FIG is not pushing misinformed positions.

7. When we look at two categories, it's tempting to hammer all
standards into one or the other. Realistically, depending on how you
define them, a standard can straddle both so we should be careful
about declaring a standard that should be rigid as something open to
incremental change, and vice versa. It might be possible to define the
voting members intent within a standard to avoid future ambiguity and
challenges.

Paddy
Pádraic Brady

http://blog.astrumfutura.com
http://www.survivethedeepend.com
Zend Framework Community Review Team
Zend Framework PHP-FIG Representative

[Jason Judge]

One thing that I not not seen mentioned yet - and this may be out of scope here - is versioning according to PHP versions.

PSR-0 describes how autoloading should work on PHP5.3, and presumably that can be extended to PHP5.4, 5.5 etc. without any drastic changes. But then PHP6 is out and autoloading is handled in a completely different way. At that point, PSR-0 would no longer apply to PHP6 and a new recommendation would be written. However, would that *supercede* PSR-0, or would PSR-0 continue to apply to the PHP5.x track, and be defined as still pretty much alive for all PHP5.x frameworks, with a new PSR starting an entirely new track for PHP6?

In other words, is there scope for versioning to take into account external conditions such as the PHP version, and for a PSR to be split down several paths for different PHP versions, neither of which supersede each other?

-- Jason


On Wednesday, 27 February 2013 07:07:22 UTC, Ryan Parman wrote:

https://github.com/php-fig/fig-standards/pull/93/files

This is my attempt at drafting a bylaw to address how we handle updates, versions, and replacements of existing PSRs.

It was born to address some of the questions around the proposed vote to "adjust" PSR-2, but also think about the future of the group's work.

--

Ryan Parman

Geek. Writer. Music Lover.

http://ryanparman.com

"Illiteracy will not be defined by those who cannot read and write, but by those who cannot learn and relearn." — Alvin Toffler

[Pádraic Brady]

Hi Jason,

As a substantive change, I would presume it to belong to a new PSR
that does not invalidate or replace the existing PSR0 for PHP5 uses.
Versioning denotes obsolescence by definition which is cannot apply to
any standard that remains both useful and applicable. Technically, you
can't even mark PSR-0 obsolete ever until we reach such a time that
the use of PHP5 has gone the way of the dodo.

Paddy

--

Pádraic Brady

http://blog.astrumfutura.com
http://www.survivethedeepend.com
Zend Framework Community Review Team
Zend Framework PHP-FIG Representative

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.

> To view this discussion on the web visit
> https://groups.google.com/d/msg/php-fig/-/ELusTj1IQh0J.

[Drak]

On 1 March 2013 11:54, Paul Dragoonis <drag...@gmail.com> wrote:

To partially answer you Andrew, all discussions should be on the mailing list, github is just for making PR's

But it's more complex than that because we do discuss PR on github..... and it does get confusing...

Regards,

Drak

[Andrew Eddie]

What Paul is saying is only discuss on the mailing list so we prevent the confusion.

So, there are a number of different scenario's here - similar but a little different. How do we want to approach this?

A. Do we continue trying to reach consensus on just one draft?

B. Do we work on two or three variations, perfect them individually, and then work out which one is most likely to pass a vote? For example, I prefer an ISO-like model, others prefer a Python model, others RFC - should we split the thread and perfect the difference ways of approach it, while keeping an eye on how each of is evolving?

I'm working on the assumption that this is going to take some weeks to sort out. And I'm just trying to work out what is the most efficient way to have this conversation.

Thanks in advance.

Regards,

Andrew Eddie

[Larry Garfield]

Working out a good governance model only takes weeks if you rush it.  Good governance models are hard.  They don't get figured out in a weekend of mass emailing by those who are otherwise bored that weekend.

I would recommend we take a step back, allow ourselves to take the time to "get it right", and work through ideas in detail.  And, in person.

I won't be attending phpTek this year (due to it being immediately before DrupalCon and my company having a vacation blackout as a result), but it's in my home town (Chicago is...) so I can definitely make it out for after-hours meetups.  This group started in a hotel room at phpTek.  How feasible would it be to have a summit at phpTek this year to discuss these questions in person?

To be clear: I'm not suggesting that "those who can't come to phpTek have no input".  But I've been through many in-person sprints, both development focused and process focused, and in-person conversation is about 10x as productive as email.  How we then handle communication from that meeting is also critically important.  I've seen that go very well and very horribly.  I'm willing to help organize/coordinate something Friday evening or Saturday for phpTek if others are interested.

--Larry Garfield

[Andrew Eddie]

On 3 March 2013 07:41, Larry Garfield <la...@garfieldtech.com> wrote:

Working out a good governance model only takes weeks if you rush it.  Good governance models are hard.  They don't get figured out in a weekend of mass emailing by those who are otherwise bored that weekend.

I didn't specify the number of weeks. I'm if we have something by mid-year we'll be going well. I didn't mean weeks - plural - two.

 

To be clear: I'm not suggesting that "those who can't come to phpTek have no input".  But I've been through many in-person sprints, both development focused and process focused, and in-person conversation is about 10x as productive as email.  How we then handle communication from that meeting is also critically important.  I've seen that go very well and very horribly.  I'm willing to help organize/coordinate something Friday evening or Saturday for phpTek if others are interested.

I was going to suggest break-out groups, but I thought that might be a bit of a stretch. I'm happy to do something via skype - an hour meeting once a week for however long it takes? 

Regards,

Andrew Eddie