[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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



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

 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.