Re: [Xen-devel] Migrating key developer docs to xen.git sphinx docs and refreshing them in the process

[Julien Grall <julien.grall@arm.com>]

Hi Stefano,

On 6/24/19 9:23 PM, Stefano Stabellini wrote:
> On Mon, 24 Jun 2019, Julien Grall wrote:
>> Hi,
>>
>> On 24/06/2019 19:03, Stefano Stabellini wrote:
>>> On Mon, 24 Jun 2019, Lars Kurth wrote:
>>> I think we all agree by now that maintaining up-to-date docs on the wiki
>>> and keeping them in sync with code changes is hard. I see moving things
>>> from the wiki to xen.git as a great improvement. We have a few Xen on
>>> ARM docs that are worth importing from the wiki:
>>>
>>> https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions
>>
>> I agree for this but ...
>>
>>>
>>> And all the board specific docs linked from it, such as:
>>>
>>> https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions/qemu-system-aarch64
>>> https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions/FastModels
>>> https://wiki.xenproject.org/wiki/HiKey960
>>
>> ... I think it is a pretty bad idea to import board specific docs. There
>> are a lot of way to build components for a given board and I am worry of
>> the overheard for the maintainers to look/maintain the documentation. It
>> also brings the question of the acceptance/removal of
>> a board documentation.
> 
> That problem can be solved by specifying an appropriate maintenance
> model for those documents.
> 
> 
>> Instead we should provide generic guidance/troubleshoot to the user.
>> Anything board specific could be maintain on the wiki by someone caring
>> about the board without having us to gate it.
> 
> If we move the docs to xen.git it doesn't immediately imply that the
> REST maintainers need to "gate" them. We could make the existing
> curators of those pages the maintainers for those files, for example. We
> can come up with mode ideas. We could even leave them unmaintained.

I don't think I want to add a random person as a maintainer in xen.git. 
So at best we would need a new role.

> 
> The point here is that we can be flexible and creative about the way to
> maintain the docs on xen.git. But as a technology is certainly better
> than the wiki: we don't have to keep them all up-to-date with the code,
> but at least this way we have a chance (if we want to). If we leave them
> on the wiki, there is no chance.

I can't see how xen.git is going to be better if "we don't have to keep 
them all up-to-date".

But my point here is most of the board should be trivial. The most of 
the non-trivial setup require non-upstream patch. While I am happy to 
see that on the wiki, I think xen.git should not promote such 
configuration at all. We are working upstream, not with 
unknown/untrusted stack.

For some working fully upstream, I don't think xen.git should promote 
any distros/versions of the kernel. However, this is ok on the wiki.

Cheers,

-- 
Julien Grall

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel