Bug reporting section?
pmorch opened this issue · 5 comments
Please add a section about where to submit bugs. Once the README makes it into a tarball it may not be obvious where the author wants me to submit bugs reports.
Similarly there should be a link to the canonical homepage.
Hey, this is a good point.
Do you have any example of a type of project where tarball does not have the information?
E.g. in NPM packages that information is usually held in the package.json file.
In my opinion: The README should contain the most import parts of the documentation. URLs for bug reporting, home page and code repository match the criteria of "the most import parts of the documentation" regardless of whether or not they can be found somewhere else too.
I don't have an example where the tarball does not have this information even without the README. But couldn't that be said for almost all of the README? I don't think that "you can find this in another file" is a valid reason to not put it into the README. The package.json file also contains this and other useful information such as the name of the project and license information. For npm packages this information is in packages.json, for java projects it's in META-INF/MANIFEST.MF for perl modules it can be any number of places and for other formats in other places. That doesn't mean that it shouldn't be in the README too. Isn't the whole idea of the README to collect all this information in a central place that is independent of project format?
(Also: I just noticed from looking at node_modules/json-schema/package.json that in addition to bug reporting URLs and the canonical homepage, the repository URL should probably also be included in the README :-) )
As always: Take what you like and leave the rest.