[RFC] \PHP namespace usage heuristics

  110711
June 24, 2020 00:30 larry@garfieldtech.com ("Larry Garfield")
Greetings, Internalians.

There has been much talk of the \PHP namespace of late, including one unsuccessful RFC.  In the discussion, the pushback broke down into two main camps:

* We should never namespace anything ever.
* We can namespace things but we need something more concrete than "RFCs can namespace things if they feel like it."

I can't do much about the former, but the latter is a solvable problem.  To that end, Mark Randall and I have put together a new RFC on the topic, based on a fruitful discussion in Room 11 a few weeks ago to brainstorm what actual guidelines should be for what goes where.

https://wiki.php.net/rfc/php_namespace_policy

This proposal provides guidance to short circuit future subjective bikeshedding, while still leaving some wiggle room for case-by-case evaluation as needed.  That makes it different from prior attempts that did not provide clear guidance for future RFC authors.

The specific guidelines offered may or may not appeal to you; those are open to discussion (within reason; we don't want to end up back in "do whatever" land as we know that won't help), but the more important point is that clear guidelines are provided.

Also of note, although it uses existing code to demonstrate where classes *would* go under this plan it does not immediately move anything.  Those are left for future RFCs that would have to stand or fall on their own merit.  It also provides for a very long grace period for any such transitions to minimize disruption.

The intent is to bring this proposal to a vote in time for 8.0's freeze one way or another, even though it's unlikely to have any impact on 8.0 itself.  It's still a convenient deadline.

*dons flame retardant suit*

-- 
  Larry Garfield
  larry@garfieldtech.com
  110718
June 24, 2020 19:32 rowan.collins@gmail.com (Rowan Tommins)
On 24/06/2020 01:30, Larry Garfield wrote:
> * We should never namespace anything ever. > * We can namespace things but we need something more concrete than "RFCs can namespace things if they feel like it." > > I can't do much about the former, but the latter is a solvable problem. To that end, Mark Randall and I have put together a new RFC on the topic
Hi Larry, Thanks for moving forwards with this. To stretch an analogy, I think we're better off picking out the colour scheme for this bikeshed in advance, rather than just resolving to buy some paint when we need it. :) One section that gave me pause reading the RFC was this: > A component namespace is “claimed” by the RFC that first uses it. Once claimed, that component namespace may only be used only by that RFC or future RFCs that extend that one in a natural way. PHP RFCs tend to describe a change rather than a full feature, and once accepted are more a historical record of the change than a living reference. Perhaps it would make sense to create an IANA-style "registry" of reserved "component namespaces", so that RFCs could add, and more rarely amend, entries in a central location. This doesn't need to be elaborate - just a table on a wiki page somewhere, with columns such as name, usage definition, status (e.g. unused but reserved for forward/backwards compatibility), and maybe notes on naming conventions within the component (use of sub-namespaces, suffixes, etc). One thing the RFC doesn't tackle in detail is what we might call The PECL Question: what are the processes when an extension moves from PECL to php-src (like ext/sodium) or from php-src to PECL (like ext/mysql)? For moves into PECL, the RFC says that the component namespace "remains reserved". If we were maintaining a registry, this could include links to PECL with appropriate status notes. For moves out of PECL, it's trickier. If we have PECL extensions listed on the registry, we could have some way to register them *before* the extension is added to core; but I'm not quite sure what that process would look like, and what kind of endorsement it would imply of the extension. If we don't do that, what would happen when an extension becomes part of core and needs to rename functionality from "Foo\Something" or "SomeCorp\Foo\Something" to "PHP\Foo\Something"? One answer would be to follow the same process as renaming functionality already in core - i.e. include the old names as aliases, subject to deprecation over a major version cycle. This would help users migrating from the PECL extension, but users of "vanilla" php-src might be confused why there are two names. Worse, it would defeat part of the point of the PHP\* namespace, since php-src would be claiming names outside it which could conflict with other projects. Perhaps a cleaner approach would be to add the extension with only the new PHP\*  names, and provide a userland polyfill for users upgrading from the PECL extension? Regards, -- Rowan Tommins (né Collins) [IMSoP]
  110720
June 24, 2020 23:11 larry@garfieldtech.com ("Larry Garfield")
On Wed, Jun 24, 2020, at 2:32 PM, Rowan Tommins wrote:
> On 24/06/2020 01:30, Larry Garfield wrote: > > * We should never namespace anything ever. > > * We can namespace things but we need something more concrete than "RFCs can namespace things if they feel like it." > > > > I can't do much about the former, but the latter is a solvable problem. To that end, Mark Randall and I have put together a new RFC on the topic > > > Hi Larry, > > Thanks for moving forwards with this. To stretch an analogy, I think > we're better off picking out the colour scheme for this bikeshed in > advance, rather than just resolving to buy some paint when we need it. :)
Ha! An apt analogy, yes.
> One section that gave me pause reading the RFC was this: > > > A component namespace is “claimed” by the RFC that first uses it. > Once claimed, that component namespace may only be used only by that RFC > or future RFCs that extend that one in a natural way. > > PHP RFCs tend to describe a change rather than a full feature, and once > accepted are more a historical record of the change than a living > reference. Perhaps it would make sense to create an IANA-style > "registry" of reserved "component namespaces", so that RFCs could add, > and more rarely amend, entries in a central location. > > This doesn't need to be elaborate - just a table on a wiki page > somewhere, with columns such as name, usage definition, status (e.g. > unused but reserved for forward/backwards compatibility), and maybe > notes on naming conventions within the component (use of sub-namespaces, > suffixes, etc).
I didn't want to over-reach, as I am not familiar enough with other Wiki processes etc. to know what the rules would be for establishing such a registry. I agree it's a good idea, though, if someone can suggest workable logistics. A wiki page or a page in docs would both make sense to me.
> One thing the RFC doesn't tackle in detail is what we might call The > PECL Question: what are the processes when an extension moves from PECL > to php-src (like ext/sodium) or from php-src to PECL (like ext/mysql)? > > For moves into PECL, the RFC says that the component namespace "remains > reserved". If we were maintaining a registry, this could include links > to PECL with appropriate status notes. > > For moves out of PECL, it's trickier. If we have PECL extensions listed > on the registry, we could have some way to register them *before* the > extension is added to core; but I'm not quite sure what that process > would look like, and what kind of endorsement it would imply of the > extension. > > If we don't do that, what would happen when an extension becomes part of > core and needs to rename functionality from "Foo\Something" or > "SomeCorp\Foo\Something" to "PHP\Foo\Something"? > > One answer would be to follow the same process as renaming functionality > already in core - i.e. include the old names as aliases, subject to > deprecation over a major version cycle. This would help users migrating > from the PECL extension, but users of "vanilla" php-src might be > confused why there are two names. Worse, it would defeat part of the > point of the PHP\* namespace, since php-src would be claiming names > outside it which could conflict with other projects. > > Perhaps a cleaner approach would be to add the extension with only the > new PHP\*  names, and provide a userland polyfill for users upgrading > from the PECL extension?
Mark had discussed having a \PHP\Ext\ namespace for extensions. I deal with extensions rarely enough that I don't have a strong opinion on the matter. I'm fine with no Ext segment, but if others feel strongly about having it that's good too. Whatever is agreeable works for me. We could also pre-reserve a namespace for PECL packages in general to use if that makes sense to people. For transitioning in/out, my feeling is: * On the way in, it's a new feature for php-src so follows the same rules as any other new php-src code. * User-space polyfills should be a reasonable and straightforward thing to do *most* of the time, so that's fine. * On the way out, the namespace remains reserved for a while so a user-space polyfill is just as viable. * These are heuristics, not absolute rules, so if a particular extension really really has need to be different that's OK, and we explicitly give ourselves wiggle room should that be needed. The goal here is to make it clear what the default policy is and where the burden of proof is to demonstrate a need to be non-default. --Larry Garfield
  110746
June 27, 2020 16:07 mike@newclarity.net (Mike Schinkel)
> On Jun 23, 2020, at 8:30 PM, Larry Garfield <larry@garfieldtech.com> wrote: > > Greetings, Internalians. > > There has been much talk of the \PHP namespace of late, including one unsuccessful RFC. In the discussion, the pushback broke down into two main camps: > > * We should never namespace anything ever. > * We can namespace things but we need something more concrete than "RFCs can namespace things if they feel like it." > > I can't do much about the former, but the latter is a solvable problem. To that end, Mark Randall and I have put together a new RFC on the topic, based on a fruitful discussion in Room 11 a few weeks ago to brainstorm what actual guidelines should be for what goes where. > > https://wiki.php.net/rfc/php_namespace_policy > > This proposal provides guidance to short circuit future subjective bikeshedding, while still leaving some wiggle room for case-by-case evaluation as needed. That makes it different from prior attempts that did not provide clear guidance for future RFC authors. > > The specific guidelines offered may or may not appeal to you; those are open to discussion (within reason; we don't want to end up back in "do whatever" land as we know that won't help), but the more important point is that clear guidelines are provided. > > Also of note, although it uses existing code to demonstrate where classes *would* go under this plan it does not immediately move anything. Those are left for future RFCs that would have to stand or fall on their own merit. It also provides for a very long grace period for any such transitions to minimize disruption. > > The intent is to bring this proposal to a vote in time for 8.0's freeze one way or another, even though it's unlikely to have any impact on 8.0 itself. It's still a convenient deadline. > > *dons flame retardant suit* >
This looks really good Larry. Very well thought-out. If I could vote it would be a definitive "Yes." -Mike