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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Mon, 24 Jun 2019, Julien Grall wrote:
> 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.

This is a good point, taking into account the current governance model.
We could use R: for that?


> > 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".

That's because a contributor could add a patch at the end of a series to
update one of the docs, even if the doc in question comes with no
promises of being 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.

I would like to see the wiki disappear completely in the long term. As
we are moving more content to xen.git, it is not a good idea to have two
places where we keep information, for similar reasons why you suggested
to use in-code comments instead of docs to document interfaces. It
just takes more efforts to maintain information in two places and they
tend to get out of sync with each others.

If we make the wiki go away (I hope so), we'll need a place to store the
Arm board-specific documents, and other tutorials.

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