Encourage lean packages

[raphaelstolt]

Release/dist packages MUST NOT contain repository meta data files like CONTRIBUTING , README, command-line executables related to the package its release process, and so on.

See LeanPackageValidator for more details.

[Revisor]

Can you provide an example of what is "a lean package"? I read your link but don't understand it.

[raphaelstolt]

A lean package is a released package that does only contain the minimal required code / artifacts for it to work.

For this standard PHP package skeleton this would be:

$ tree .
.
├── (LICENSE)
├── (bin)
├── composer.json
├── (config)
├── (public)
└── src

(*) optional

With the presence of the directories bin, config, and public being dependent on the type of the package. And the presence of the LICENSE file being dependent on the chosen license model of the package.

This can be achieved by utilising export-ignore patterns in a .gitattributes file like shown next.

.ctl.cache export-ignore
.editorconfig export-ignore
.gitattributes export-ignore
.github/ export-ignore
.gitignore export-ignore
.gitmessage export-ignore
.php_cs export-ignore
.travis.yml export-ignore
bin/application-version export-ignore
bin/release-version export-ignore
bin/start-watchman export-ignore
bin/travis/* export-ignore
CHANGELOG.md export-ignore
example/ export-ignore
phpunit.xml.dist export-ignore
README.md export-ignore
tests/ export-ignore

[pmjones]

@raphaelstolt -- Can you link to some literature that talks about "lean" packages in general?

Also, I don't know how common this is. At a minimum, analyzing for this would require examining the .gitattributes of each package in the sample, then determining if the "right" files had been excluded. Then it would need to be able to be applied regardless of the SCM system (Git, Hg, Svn, FutureSystem, etc).

If it's not commonly-done, and can't be abstracted away from a particular SCM toolset, then it's probably not a candidate for the standard.

[pavarnos]

i like the idea: too often packages come with a lot of extra cruft / clutter eg tools used to develop the package or config files for those tools. These clutter the namespace and can interfere with IDEs eg with phpStorm, i have to manually tell it to ignore symbols in some .phar files a package developer has forgotten to exclude from release because they are duplicates of other packages in my composer.json.

[raphaelstolt]

@pmjones So there are two links I can provide you. One from reddit and one that got me started using .gitattributes.

I can also remember a debate and decision to not do this for the Symfony components, would really like to know their reasoning against it.

A quick and shallow Google search reveals that this feature seems to be Git specific. However I got a gut feeling that the majority of PHP packages are using a Git based SCM and that lean packages are definitively a goal to strive for. How about making it a MUST for Git based packages and a RECOMMEND or SHALL for the other SCM systems?

[pmjones]

That's interesting reading; thanks.

On furhter consideration, though, it occurs to me that this, like #6 , might well be out-of-scope for a standard that intends only to define top-level names for common directories and files.

[pmjones]

@raphaelstolt @pavarnos Any further thoughts here? I am leaning toward closing this as "out of scope" but I want to make sure I'm not missing something else important.

[raphaelstolt]

Feel free to close it.