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. > OTOH, I'm not sure how well 'I fixed these coding styles issues and > pushed the patch' translates to the merge request review. I don't think it does. However, once syntax-check is something that is run automatically at MR time and which gates merge, contributors are more likely to address the issue themselves before a reviewer gets around to looking at the changes. -- Andrea Bolognani / Red Hat / Virtualization
