On Mon, Apr 06, 2020 at 10:34:53AM +0200, Andrea Bolognani wrote: > On Fri, 2020-04-03 at 19:35 +0200, Ján Tomko wrote: > > On a Friday in 2020, Andrea Bolognani wrote: > > > Everything else looks good, but there's the obvious caveat that we > > > can't merge the commit as-is until we have actually moved to GitLab. > > > > > > Since that could take a while, and locking down the GitHub > > > repositories is already a good idea, maybe point people to > > > > > > https://libvirt.org/hacking.html > > > > > > in the meantime? > > > > As danpb mentions in the cover letter, CONTRIBUTING.md should be easily > > discoverable on GitLab. We [0] should somehow put the brief instructions > > there (like README-hacking) and not scare drive-by contributors with > > the giant hacking.html. > > The problem with hacking.html is that it's a catch-all location that > where a hodgepodge of concepts, which are related to various degrees, > are documented: > > * various resources related to libvirt development, such as the > primary git repository and the libvirt project on Zanata; > * how to write good commit messages; > * how to split changes into multiple commits; > * other requirements, such as having DCO information; > * how to run the test suite; > * how to fix issues reported by valgrind; > * how to send patches to libvir-list; > * which languages are appropriate for new code; > * what's our code style; > * which GLib APIs should be used instead of libvirt-specific APIs > that in most cases have been dropped already; > * governance rules; > > all of it sprinkled with useful tips such as which options to use > when running 'git diff'. No wonder it's overwhelming. > > I think we should rethink how we organize this information. For > example, while the fact that git-publish should be used to post > patches is, at least until we complete the move to GitLab, critical > information to new contributors, but detailed steps for setting up > mail delivery in git could live in a separate guide linked to from > the main document, so that only those who are not already familiar > with a mail-based development workflow need to access it; along the > same line, how to run the test suite should be documented prominently > but how to solve issues reported by valgrind doesn't. > > Of course the biggest offender is the coding style, which takes up > most of the page. That could be split off to a separate page too, > under the IMHO sane assumption that even someone unfamiliar with the > codebase will naturally get very close to adhering to it through a > combination of looking at existing code and addressing the issues > reported by 'make syntax-check'; in the longer run, we should really > invest some time building a clang-format profile that approximate > our current coding style and just require that all contributions > go through that tool, thus making the page mostly obsolete. > > 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, but I don't think that's a strict pre-requisite for adding a simple CONTRIBUTING.md file. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
