|
[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 25/06/2019 01:02, Stefano Stabellini wrote: 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_ExtensionsI 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? I am not entirely sure, this still mean "THE REST" will be in charge of it. Anyway, this is not the biggest problem here. 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. I think this is going the wrong direction. The goal of using xen.git is to try to keep the documentation 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. Removing the wiki is an honorable goal, however I don't think all the wiki is suitable for xen.git. The Arm board-specific documents is an example. You actually haven't addressed my concern above. If you look at the wiki, a lot of them ([1], [2], [3]) contains non-upstreamed work or non-upstreamable hack. For those containing only upstream work [4], the example is focusing on one set of distros. In the case of QEMU, I already had some people asking whether it is possible to use without U-boot. Why would we promote Ubuntu and not something else? Overall, there are so many configurations possible (kernel, u-boot, distributions) that it does not makes sense to keep track of that in xen.git. Instead, I think we should write generic doc on how to boot Xen on a U-boot/UEFI setup and inviting the users to look into more details for his board. Cheers,[1] https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions/Salvator-X [2] https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions/Stout [3] https://wiki.xenproject.org/wiki/HiKey[4] https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions/qemu-system-aarch64 -- Julien Grall _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxxxxxxxxx https://lists.xenproject.org/mailman/listinfo/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |