Proposal: PHP Evolving Recommendations (PERs)

[Larry Garfield]

We've been talking about "living specs" for a long time. Let's finally define a process for that:

https://github.com/php-fig/fig-standards/pull/1235

I won't resummarize it here, as the issue already does so.

My expectation is that out of the gate, we'd see something like this:

* PER-CodingStandards (uses PSR-12 as a basis, updating it for each new PHP release.)
* PER-Cache Utils (maintains the cache-util and simplecache-util libraries.)
* PER-HTTP (maintains the various PSR-7/15/17/18 util libraries.)
* PER-DocBlocks (would replace PSR-19, the tag library, but NOT PSR-5, the parsing rules, which still need to get finished.)

And should we decide that a "type library" (enums, etc.) is a reasonable thing for us to do, it would get its own PER as well.

Discuss.

--
Larry Garfield
la...@garfieldtech.com

[Matthew Weier O'Phinney]

My main question is why the Util libraries would move to the PER process.

Currently, these have been developed to provide features complementary to a given standard:

- cache-util and simplecache-util provides boilerplate that will be used in most implementations, as well as default "in memory" implementations.

- http-util provides constants used for request methods and response status codes

In each case, I'd argue they're less "evolving standards" as they are libraries tracking common usage or tracking non-FIG standards to provide commonly used artifacts. In other words, they are _libraries_, not _recommendations_.

Otherwise, the rest of this looks fantastic! Thanks for putting this together!

--
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 view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/0f07cf13-80e3-436d-b950-9cb7d926741b%40www.fastmail.com.

--

Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/

he/him

[Larry Garfield]

On Thu, Aug 12, 2021, at 10:42 AM, Matthew Weier O'Phinney wrote:
> My main question is why the Util libraries would move to the PER process.
>
> Currently, these have been developed to provide features complementary
> to a given standard:
>
> - cache-util and simplecache-util provides boilerplate that will be
> used in most implementations, as well as default "in memory"
> implementations.
> - http-util provides constants used for request methods and response
> status codes
>
> In each case, I'd argue they're less "evolving standards" as they are
> libraries tracking common usage or tracking non-FIG standards to
> provide commonly used artifacts. In other words, they are _libraries_,
> not _recommendations_.
>
> Otherwise, the rest of this looks fantastic! Thanks for putting this together!

Mainly because right now we have no process for util libraries; their ownership and management is entirely undefined (as witnessed by the simpelcache-util library being entirely empty and abandoned for no particular reason). I figure if we establish a process for them it would probably look an awful lot like the PER process, so I tossed them in together.

If we wanted to keep them separate, what would that look like?

--Larry Garfield

[Michael C]

With the util libraries, I'd concur with Matthew. 

Right now it is kind of undefined I agree but I also am not sure that is necessarily an issue to be honest. What is the problem solved by creating formal processes around the util libraries?

You call out simplecache-util, I don't think the problem there is a lack of formal process for util libraries. It appears to either be that it's just not necessary/no demand for anything there or nobody is willing to put the time into doing it. I don't think a formal process is the answer there?

Also, most of the util libraries need very little to no maintenance as they are designed to be kept simple and uncontroversial. Maintaining a group around each of those seems quite heavy and probably would result in more time spent on the admin than the actual project itself.

I think conceptually something like what is proposed [PERs] make sense for things like coding standards but I would note that it is also very helpful to be able to clearly delineate versions and call out that one is meeting a standard (PSR-12 or PSR-2). Nobody wants standards to be... too fast moving or agile, perhaps a version a year at maximum velocity for example.

So perhaps when establishing a PER there is a defined maximum release schedule velocity and a strict scope of what 'evolution' looks like (e.g. stuff is only added due to new or mutated PHP functionality, to clarify, or to reflect changes in the ecosystem for coding standards, not just add whatever you wish whenever you want).

I also think backwards compatibility [in the sense of not changing things but only being additive as any standard change is a BC break in the usual sense of the word] and simplistic versioning (e.g. PER-CodingStandards V1, V2, V3 where they are additive or clarificatory, not mutating) I think would be critical to the success of the idea of PERs, over something like semantic versioning which automatically implies three levels of versioning and the idea of "BC" breaks. I can't see people wanting to be maintaining automation tools or projects that are dealing with a standard that is being updated too frequently or has complex versions determining which versions of the standard are supported (tooling) or which version is implemented (projects).

Many thanks,

Michael

--
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 view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/0a7fec5a-864d-4b44-b24b-717d9e7e3343%40www.fastmail.com.

[Vincent de Lau]

As mentioned in the pull request, I feel a need to make a distinction between artefacts/deliverables and the process (working groups). Allow me to brainstorm a bit:

• PHP-FIG recognizes three types of artefacts:
  • PSR: requires a controlled change process, where acceptance and errata are subject to CC approval.
  • PER: only requires initial acceptance by CC, can evolve over time without explicit CC approval.
  • auxilary material, including util libraries
• All artefacts are owned by the CC.
• Each artefact should have an Editor or Maintainer appointed by the CC.
• The CC can form (or approve formation of) a WG.
• CC can delegate maintenance of each artefact to a Working Group.
• CC can request a WG to prepare a new artefact. If no suitable WG is available, a new WG must be formed.
• A WG has at least three members members.
• A WG has one WG Lead (currently the editor for a PSR).
• A WG has a CC Sponsor.
• Editors and Maintainers are automatic WG members of the WG that is responsible for the artefact.
• The CC can terminate a WG when it the the WG not longer needed.
• When a WG is terminated, artefacts keep their Editor or Maintainer.

Obviously, this is not a complete proposal, but I hope that the direction is clear.

--

Vincent

[Larry Garfield]

On Sun, Aug 15, 2021, at 10:34 AM, Vincent de Lau wrote:
> As mentioned in the pull request, I feel a need to make a distinction
> between artefacts/deliverables and the process (working groups). Allow
> me to brainstorm a bit:

> * PHP-FIG recognizes three types of artefacts: * PSR: requires a

> controlled change process, where acceptance and errata are subject to
> CC approval.

> * PER: only requires initial acceptance by CC, can evolve over time
> without explicit CC approval.
> * auxilary material, including util libraries
> * All artefacts are owned by the CC.
> * Each artefact should have an Editor or Maintainer appointed by the
> CC.
> * The CC can form (or approve formation of) a WG.
> * CC can delegate maintenance of each artefact to a Working Group.
> * CC can request a WG to prepare a new artefact. If no suitable WG is

> available, a new WG must be formed.

> * A WG has at least three members members.
> * A WG has one WG Lead (currently the editor for a PSR).
> * A WG has a CC Sponsor.
> * Editors and Maintainers are automatic WG members of the WG that is
> responsible for the artefact.
> * The CC can terminate a WG when it the the WG not longer needed.
> * When a WG is terminated, artefacts keep their Editor or Maintainer.

> Obviously, this is not a complete proposal, but I hope that the
> direction is clear.

Hm. This is a somewhat larger refactor than just adding a PER process. I like the thrust of it, but it's going to require a bit more reworking of the bylaws to make it all fit together nicely.

I'm game to try and set up something for the above if others are on board with it.

--Larry Garfield

[Woody Gilk]

On Thu, Aug 12, 2021 at 10:42 AM Matthew Weier O'Phinney <mweiero...@gmail.com> wrote:

My main question is why the Util libraries would move to the PER process.

Currently, these have been developed to provide features complementary to a given standard:

- cache-util and simplecache-util provides boilerplate that will be used in most implementations, as well as default "in memory" implementations.

- http-util provides constants used for request methods and response status codes

In each case, I'd argue they're less "evolving standards" as they are libraries tracking common usage or tracking non-FIG standards to provide commonly used artifacts. In other words, they are _libraries_, not _recommendations_.

I understand the point you are trying to make here, but I also worry that packages like `http-util` have become rather stagnant and are (oddly) difficult to work with. For instance `StatusCodeInterface::STATUS_OK` is incredibly verbose. Something like `HttpStatus::OK` would be far more elegant to work with. And when Enums are available, this package would really benefit from adopting them.

My point here is that even if the util packages are "libraries" they don't appear to update and evolve like I would expect a library to.

--
Woody Gilk
https://www.shadowhand.com

 

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAJp_myWyGG6Ypve1aaffwTwfwxrfn4do0c%3DJ2G4hZfY-Kr7wJA%40mail.gmail.com.

[Larry Garfield]

Thank you everyone for the feedback here and on GitHub. Based on that, I've refactored the bylaws quite a bit more to support a cleaner way to define the PER process, and to split auxiliary resources (eg, util libraries) off to their own setup. The full changelog is in the PR:

https://github.com/php-fig/fig-standards/pull/1235

Feedback, round two!

--Larry Garfield

[Ken Guest]

Hi,

I think having Evolving Proposals would be a good thing. 

Then people only have to bookmark the PER once and revisit it when appropriate instead of having to follow a trail to see what the most up-to-date recommendation is.

For example, somebody coming back to PHP after a while might not know that PSR-12 exists but knows about PSR-2. When they find PER-CodingStandards they can be sure of the most recent PSR in that area.

I mentioned this on Discord today. Alessandro Lai suggested that for this scenario in relation to code, we can bind that to new major versions, for CS maybe we can use a meta-package so projects can declare with a constraint their "version" of adherence to the PER.

I think that for deprecated PSRs -  in this instance PSR 2 -  we could expand the Deprecated Notice block to identify and link to the pertinent PSR.
This would mean someone will hopefully have fewer steps to go through to find the most recent relevant PSR.

As an example the message "Deprecated - As of 2019-08-10 PSR-2 has been marked as deprecated. PSR-12 is now recommended as an alternative." would be changed to "Deprecated - As of 2019-08-10 PSR-2 has been marked as deprecated. Please consult PER-CodingStandards to quickly identify the most recent applicable PSR. At the time of this update, PSR-12 is the new Recommendation superseding this one (PSR-2)."

Regards,

Ken

--
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 view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/fa785737-c508-4e41-a799-790e2dd487a0%40www.fastmail.com.

--

http://about.me/kenguest/

[Chuck Burgess]

I added some tiny correction comments, but overall, I like it 😎👍

CRB

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAKcc2m_67PHxwd9GwVOojpXBm9Us4%3DQHHLsUk3n%3DLHYtV0cWVg%40mail.gmail.com.

[Alessandro Chitolina]

Great work on this Larry! 👍

Alessandro

[Alessandro Lai]

Sorry for the late review... Larry, I've added two small comments, nothing fundamental.

Great work!