Re: [Qemu-devel] KVM call agenda for April 05

[Harsh Bora <harsh@linux.vnet.ibm.com>]

On 04/06/2011 02:00 AM, Anthony Liguori wrote:
> On 04/05/2011 03:25 PM, Peter Maydell wrote:
>> On 5 April 2011 14:14, Stefan Hajnoczi<stefanha@gmail.com> wrote:
>>> This stems from the fact that development is centered around the
>>> mailing list. Some folks have put technical documentation on the wiki
>>> but a lot simply happens on the mailing list.
>>> I'm unsure how we can sustainably keep the wiki up-to-date on detailed
>>> code internals knowledge. Any suggestions, any examples of projects
>>> doing this successfully?

Well, Libvirt community does follow the practice of requiring the patch 
submitter to provide enough documentation within docs/ folder or in the 
patch itself. The commiter ensures that the docs/ are updated with the 
patch desc if docs/ are not updated as a part of the patch.
See http://libvirt.org/hacking.html#patches

>> Another approach would be to try to increase the use of docs/
>> for technical code internals information. The advantage would be
>> that we could choose to require docs/ updates for design changes
>> in order for a code change to pass patch review; the disadvantage
>> would be that it's inevitably more of a pain to update.

Yes, Its better to have code and docs being updated together with the 
patches coming in, however, it will become more difficult to follow this 
practice if it is not followed regularly, for. eg, if patch A doesnt 
updates the docs as required, and a patch B which is based on Patch A 
wants to update docs, it needs to get the required docuemntation for 
patch A first before putting documentation for the patch B itself.

>
> We've been unofficially doing that for a lot of recent stuff.
>
> I don't know that that really helps with the problem of keeping it up to
> date though.

Well, as we have been doing it unofficially for recent stuff, it will be 
better to have it officially now :). It shall definitely help, as it 
gives an opportunity to even update an obsolete piece of info as 
compared to having no docs to update.
As they say, something is better than nothing !

regards,
Harsh

>
> Regards,
>
> Anthony Liguori
>
>> -- PMM
>>
>
>
>