Re: [libvirt] docs: Change or update the hacking page

On Wed, May 11, 2016 at 7:51 PM, Michal Privoznik <mprivozn(a)redhat.com&gt; wrote: > On 11.05.2016 16:01, Cole Robinson wrote: >> I've thought a bit about this too. I don't think the HACKING page is a > good >> landing page for new contributors. It _is_ useful document _everything_ > that a >> contributor might want to know, but I think we should also have a page >> specifically for a contributor quickstart which has very bare minimum > info. >> I'm not saying this is anything you need to handle :) Just figured I'd > throw >> my thoughts out. > > Agreed. Good idea! > >> >> Ideas for the hypothetical doc, which shouldn't be more than a page or > two: >> >> - building libvirt, with links to more complete docs. though one of the >> hardest bits about getting involved with any project is learning the > correct >> build incantation to make things work. I usually suggest grabbing the >> ./configure line from rpm --eval '%configure', but libvirt has autogen.sh >> --system as well, but I haven't tested it in a while > > I'd advice them to use the autogen.sh script, because I guess that rpm > produces this long command line enabling all the features supported (for > instance systemd API requiring systemd-devel and so on). In general, > when configure is run without any additional arguments, it enables all > the features that it is able to with packages currently installed in the > system. I don't think we should require newbies to install sheepdog for > instance. > >> >> - running libvirt: running libvirtd/virsh from git, maybe RPM? probably >> discouraging 'make install' unless people know what they are doing > > Correct. ./run daemon/libvirtd or ./run tools/virsh. I wouldn't mention > RPM as it would replace libvirtd they have in the system, which is a > stable one with their buggy one. They are new to the project, there > definitely gonna be some bugs in their code. > >> >> - basic steps for running make check and make syntax-check > > This should be the default. Correct. I usually join them: make all > syntax-check check. > >> >> - mention that we use git format-patch/send-email, but no instructions, > link >> them if necessary. maybe link to example mailing list postings for > guidelines >> for formatting commit messages/series > > Correct. > >> >> - A link to the BiteSizedTasks page > > Correct. > I am definitely +1 for this. Having recently gotten my first patch accepted, I would say that a contributor quickstart page which describes how to set up the bare essentials to start contributing with links to more info is a good idea. Also, anything more about changing stuff on the hacking page, like the example I had given about removing the point that mentions using plain diff or git diff? Any more points or things that should be removed, added or updated from that page? Nishith