[RFC] Change Resources/meta/LICENSE and Resources/doc/index.rst

[Tobion]

Currently the best practise for reusable bundles says

The following files are mandatory:
HelloBundle.php;
Resources/meta/LICENSE: The full license for the code;
Resources/doc/index.rst: The root file for the Bundle documentation.
These conventions ensure that automated tools can rely on this default structure to work.

I think it's time to change that. I would propose to simply say there should be

1. a LICENSE file in the root directory and a license property in composer.json
2. a README file (in any format, e.g. README.md or README.rst) in the root directory that serves as an entry point to the documentation

I think this has several advantages:

1. this is how Symfony itself is also structured. For example, the documentation of symfony bundles is not in Resources/doc but in a separate repository. So symfony does not follow it's own best practises at the moment.
2. the LICENSE file in the root is common practise in open source but Resources/meta/LICENSE is not
3. the README is also common practise, especially when using github. This also makes it independent of the format. And most bundles don't use rst format anyway from my experience but markdown, e.g. FosUserBundle. Which would also go against the current best practise.

[Tobion]

Are there actually automated tools that really rely on the current best practise folder structure?

[wouterj]

Yes: https://github.com/schmittjoh/JMSCommandBundle and https://github.com/gnugat/fossil are the ones I know.

[Tobion]

They don't rely on the folder structure but help you set it up. So the changed wording I chose still permits you to put your documentation in Resources/doc but you can also chose anything else. Because all that matters, is that it should be reachable by the root readme. Btw, gnugat/fossil also creates markdown doc AFAIK so would also now follow the current best practise.

[stof]

To complete this, KnpBundles supports both locations for the LICENSE file (and if both exist, it prefers the root file). And for the README, it supports any extension (given it uses the dedicated github API to retrieve the readme file), but then renders it as markdown

[wouterj]

The standards are now made more flexible, allowing both locations for the LICENSE file and both rst and markdown for the README file