php-fig/fig-standards — pull request #171 by simensen (2013-08-30 14:40:25+00:00)
Title: Move example implementation copy to the meta document.

I think we've talked about this issue off and on. At some point I thought we'd agreed that the example implementation should be removed from the PSR itself. I think as it is written now is probably a decent compromise (since the actual implementation is no longer actually in the PSR) but there are a few things that kinda feel weird:

> Implementations MAY contain additional features and MAY differ in how they are implemented.

Clearly implementations will be different and may have different features. As much as I originally liked this line of text, I think it was only needed if the reference implementations were actually included in the doc itself. Otherwise, it just sounds like we're saying something obvious: implementations will differ.

> For example implementations, see [Psr4AutoloaderTest.php](Psr4AutoloaderTest.php). Example implementations MUST NOT be regarded as part of the specification; they are examples only, and may change at any time.

This sounds like meta documentation and we have a place for that now. This **is** a step up from having the code actually embedded int he doc, but we can avoid any problems by simply moving this to the meta doc where I would argue it belongs.

The only reason we need to warn that they are by example only and not to be considered a spec is because we're linking to a reference implementation in the spec itself. This was what happened with PSR-0. If we remove the link to code from the spec itself I think the whole thing will be cleaner.