[libvirt] docs: Change or update the hacking page

[Michal Privoznik]

On 11.05.2016 16:01, Cole Robinson wrote:
> On 05/11/2016 02:04 AM, Nishith Shah wrote:
>> Hi everyone, sorry about the empty message above, I was typing and I pressed
>> the wrong set of keys.
>>
>> So, I was going through the contributor guidelines page[1], and after
>> discussing with Michal Privoznik, I think there are some things that need to
>> be updated. For instance, the 4th point about posting patches mentions using
>> git diff instead of git format-patch. I also feel that the workflow in general
>> should be re-written and updated with some more details. I have written a very
>> detailed post about the workflow here[2], and might pick some points up from
>> there. Please let me know what you think of it.
>>
>> Also, please post the other things  that you think should be changed on that
>> page in this thread.
>>
> 
> 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.

Michal