[libvirt] docs: Change or update the hacking page

[John Ferlan]

On 05/11/2016 12:22 PM, Nishith Shah wrote:
> On Wed, May 11, 2016 at 7:51 PM, Michal Privoznik <mprivozn at redhat.com>
> 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
> 

A link to whatever new is created and perhaps the more detailed hacking
from the "first" page (index.html) would be nice!  Every time I go
looking for the hacking page - it's a memory test to find it...

Option 1. documentation -> internals -> hacking.html

Option 2. documentation -> architecture -> API concepts (at the bottom
of the page) -> hacking.html

Option 3. bug reports -> know to click "contributor guidelines" ->
hacking.html

Option 4. Sitemap -> Contributor guidelines -> hacking.html

So on index.html, maybe some sort of "getting started section" after
"libvirt provides" that would link directly to the API, how to run, the
first time contributor, the hacker...  IOW: Direct links to what you may
need the more advanced you get. See what happens when you open a can of
penguins ;-)...

John