mindplay-dk
commented
8 months ago For the record, the examples have been commented-out, but are still present in the README, and can be seen here.
The README isn't part of the PSR though, and the PSR needs to function without it.
I think it can, but I am not 100% certain it works for everyone, so I'm leaving the content in the file for now, and leaving this issue open until a decision is made.
As I'm working on a first draft of the PSR and meta documents, most of the content in the README has been rewritten, and moved into either the PSR (in the form of RFC2119 requirements) or the meta document.
I've been getting hung up on the examples in the README though. Most of the requirements in those examples have been formalized and moved to the PSR already, but the example code itself remains in the README, as I'm not sure whether or where it should be moved.
To be clear, we're talking about these remaining sections of the README:
https://github.com/mindplay-dk/service-provider/blob/60b1ec392546b70d223f95322f728fcc680d778f/README.md?plain=1#L19-L181
The actual proposal of course will have a PSR spec and a meta document - it won't have a README.
Even though I knew this, I have been updating the README and the examples as I went over everything.
The question is whether these code examples have any place in the PSR itself?
I do not think they belong in the PSR itself - the PSR should focus on the description and requirements.
But I'm not sure if they belong in the meta document either - typically, the meta document provides a historical overview (things tried, lessons learned) as well as background and reasoning for various decisions.
I don't think I've seen a PSR that includes anything like a "tutorial", "implementation guide" or code samples?
But I suppose:
Option 1 is we move the examples into the meta document - perhaps this could be framed as "Provider Patterns", a section that provides examples of patterns commonly supported by DI containers, with the aim of explaining how these patterns are supported and can be implemented using PSR providers.
(I believe these sections were written at a time when we expected developers would hand-write providers? Although that remains an option, this approach seems like more of an "edge case" to me now - my expectation is DI containers will either create PSR providers, or we'll see dedicated provider builders that libraries can use, and so on. So I would reframe the descriptions in these examples as presenting patterns that container implementors can reference.)
Option 2 is we simply remove the examples.
As you can see (from the link above) it's a lot of content, and so it feels like a somewhat drastic decision to just make on my own.
But as said, a PSR standard does not have a README, so we need to do something. The README should be like a cover page for the in-process PSR - a wrapper that can be thrown away if the PSR becomes official. So it needs to be really short, and nothing in the README should be required to understand or consume the PSR itself.
What do you think? Do we need the examples from the README?
Could we do something different with these examples, at a later time? It almost seems like the kind of stuff you could put in an article or tutorial about PSR providers - it's useful, but perhaps that doesn't automatically mean it belongs in the PSR itself?
Would love any input on this, please. 🙏