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

[Julien Grall <julien.grall@xxxxxxx>]

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@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel