search

php-pds / skeleton

Standard PHP package skeleton.
Creative Commons Attribution Share Alike 4.0 International
2.32k stars 167 forks source link

Resources folder #12

Closed ravage84 closed 7 years ago

ravage84 commented 7 years ago

I'd like to propose the addition of the resources folder to this standard.

The resources folder, to me at least, is a folder where one can store non public, non 100 % source code" related resource material/assets etc. For example, We used such a folder for storing vendor XML schema files for a XML API client library we recently developed.

While I agree, it is not a very common folder, it is still a quite common enough one, as you can see by your own research data:

Total "resources" related: 7454

Through your iteration steps, though, you only considered the resources variant with 1424 occurrences. https://github.com/php-pds/skeleton_research/blob/1.x/results/02-dirs.txt#L82

This might be an addition for a later version of this standard, though.

pmjones commented 7 years ago

Hi @ravage84 --

First, thanks a ton for your attention to detail, and your adherence to the research results. I love it when people actually follow the work. :-)

Next, yeah, I get that a "resources" style directoryis useful. Note that the current draft does not preclude its presence in the package. There's a lot of root-level directories and files the standard does not cover, but does not require.

In the case of the count on "resources", here's the sticking point: top-level directories starting with a capital letter are presumed to be PHP namespace directories, holding PHP code. For example, when you look at the top 10 most-common directories, they are:

src/    37651
tests/  21707
Resources/  5969
config/ 5478
DependencyInjection/    4989
Tests/  3881
test/   3263
docs/   2763
bin/    2747
Controller/ 2659

Resources, DependencyInjection, Tests, Controller: all of those appear on inspection to be PHP namespaces (and as far as I can tell, framework-specific ones). As such, they get excluded on the second round. Modifying the research methodology to include Resources, then, would need to include all the others as well, and that seems unwarranted to me.

Having said that, if the name "resources" becomes common enough across the ecosystem, then yes, it would be a candidate for inclusion in a later iteration.

Do you get where I'm coming from here?

ravage84 commented 7 years ago

Resources, [...]: all of those appear on inspection to be PHP namespaces [...]

In case of Resources, I doubt that. 😼

Do you have alist of repos I could wade through to verify this for this case?

But yes, I totally get your point.

pmjones commented 7 years ago

Do you have alist of repos I could wade through to verify this for this case?

Kind of? The collected "tops" files are in tools/vendors/tops/{$vendor}/{$package}.txt; using those you should be able to find the relevant Packagist entry, and then look at its Github repo. Yes, that's an intensive piece of work. :-/

Meanwhile, I reiterate that a "resources" directory is not disallowed. It just doesn't have a required name if present at the root.

fabpot commented 7 years ago

Those directories look familiar to me :) It looks like they come from Symfony-based projects, where Resources is the directory where people can store assets (actually, anything that is not PHP code). We decided early on to keep it capitalized for consistency.

ravage84 commented 7 years ago

@fabpot

[...] where people can store assets (actually, anything that is not PHP code)

This is quite what I wanted to propose here.

ravage84 commented 7 years ago

It seems, we should consider the "res" folder, too:

https://github.com/composer/ca-bundle/tree/master/res

pmjones commented 7 years ago

So, Resources/ is not intended as PHP namespace directory for source code, even though it starts with a capital letter. That exempts it (as a special case) from the second-pass constraint, "Ignore directories starting with a capital letter, on the presumption that they are PHP namespace directories."

On that basis, it may be reasonable to revisit the analysis.

Thanks, all, for the review here!

pmjones commented 7 years ago

I have updated the research with the above thread in mind. It reveals that resources/ (or some form thereof) occurs in 11.6% of packages, warranting its explicit inclusion in the standard.

Cf. https://github.com/php-pds/skeleton_research/blob/1.x/results/05-dirs.txt