On Mon, 2020-04-06 at 10:02 +0100, Daniel P. Berrangé wrote: > On Mon, Apr 06, 2020 at 10:34:53AM +0200, Andrea Bolognani wrote: > > Anyway, back to CONTRIBUTING.md specifically: once we have improved > > and trimmed down hacking.html (contributing.html?) to a reasonable > > size, we can simply link to it. I don't think that's a strict > > dependency, however, and while our current hacking.html is clearly > > suboptimal I'd rather have issues/PRs locked down and directing > > developers to it than the current status quo. > > IMHO the CONTRIBUTING.md is something that can be fairly simple. The > important things is that it should cover directly are > > - How to submit patches > - How to report issues > - How to comply with the DCO > > Then it should provide links to information about coding style, > information around testing, information about platform portability > expectations, and other important reference material that might be > relevant. > > We can certainly split up / re-organize hacking.html more generally, I'll try to give this a shot. > but I don't think that's a strict pre-requisite for adding a simple > CONTRIBUTING.md file. I'm wary of the risk of duplicating information in multiple places. We already have some overlapping information between hacking.html and README-hacking, but that's justified by the fact that it was considered a good idea to provide "bootstrap" steps, ie. enough information to get to the point where you could build the full HTML documentation locally from a git clone. I'm no longer convinced this is that useful, because if you have a git clone you clearly have internet access and at that point you might as well jump straight to the pre-built version available on libvirt.org, but let's leave this argument for another day. What we do *not* want to have is another "quick start guide" that duplicates the information further. If our hacking.html is too overwhelming to serve as such a landing page, then we should change it so that it no longer is, not add yet another overlapping document. -- Andrea Bolognani / Red Hat / Virtualization
