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, Lars Kurth wrote:
> Hi all,
> 
> since Andy created https://xenbits.xen.org/docs/sphinx-unstable/ and 
> https://xenbits.xen.org/docs/sphinx-unstable-staging/ (sources in 
> docs/hypervisor-guide, docs/guest-guide, docs/admin-guide) I was wondering 
> whether it would not make sense to migrate some key documents in the wiki 
> (and possible some docs elsewhere in the tree) into the new structure and 
> refresh and update the documentation in the process. I am volunteering to do 
> some of the leg-work.
> 
> I started looking into what some other projects do and the following seem to 
> be sensible and lightweight examples of Information Architecture to structure 
> the content:
> * https://docs.openstack.org/infra/manual/developers.html
> * 
> https://github.com/kubernetes/community/blob/master/contributors/devel/README.md
> 
> Both are fairly lightweight and seem to be sensible guides. But before we get 
> to that level of detail, I thought it makes sense to look at what we have and 
> candidates for moving/improving/creation. However, it is clear that we need 
> two broad categories under docs/hypervisor-guide (Hypervisor developer 
> documentation): note that I don’t much care about the actual labels
> * The process of developing and contributing code
> * Setting up your dev environment, coding, and debugging
> 
> Documentation which may be worth moving or creating
> 
> Text files in tree (which are close to RST file format)
> * Xen.git:CONTRIBUTING – it seems to me that this is a candidate for moving 
> (with a note in the original file which outlines where to look for the 
> source/rendered output) – Even committers occasionally don’t seem to be aware 
> of some of the licensing related common practices we have. Giving some of 
> that content a more prominent place in a new more user friendly and modern 
> looking docset seems sensible  
> * Xen.git:INSTALL may be a good candidate which could live in the admin guide 
> and/or developer guide
> * Xen.git:CODING_STYLE and Xen.git:tools/libxl/CODING_STYLE - Note that in 
> the community call discussion Jan raised the point that we tend to not 
> document precedents for many things which are coding style related. Maybe we 
> can get a bit better 
> * Xen.git:MAINTAINERS should stay as it is, but should probably be referred 
> to appropriately in the docset
> 
> Content from the wiki (the idea would be to redirect those pages in the wiki 
> to the new locations)
> * https://wiki.xenproject.org/wiki/Asking_Developer_Questions - could do with 
> a refresh. Possibly there is also a tie in with 
> https://lists.xenproject.org/archives/html/xen-devel/2019-06/msg01518.html
> * https://wiki.xenproject.org/wiki/Compiling_Xen_From_Source - there seems to 
> be some overlap with Xen.git/INSTALL which may be worth cleaning up
> * https://wiki.xenproject.org/wiki/Xen_Project_Repositories 
> * https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches - This has 
> become a bit unwieldy and could do with some clean-up
>    * Slight overlap with Xen.git:CONTRIBUTING (around DCO and Sign-off) 
>    * Making good patches probably needs some work and maybe should be broken 
> out. It should include good examples and setting expectations of what is 
> deemed good and bad around areas where we have higher standards than other 
> projects (such as commit messages, explaining rationale for a change, 
> technical debt, ...). It should probably also cover things such as Design 
> Documentation and where to find templates, highlight existing documentation 
> and where to find it/update it, the same with text, SUPPORT.md (aka add a new 
> feature), etc.
>    * Setting up git send-email: should probably go into a section related to 
> the development environment set-up and just be referred to
>    * Using git send-email alone - we should nuke this section and focus on 
> the next section 
>    * Simplest workflow: Git format-patch, 
> add_maintainers.pl/get_maintainer.pl and git send-email - I would build the 
> bulk of the doc around this, but maybe move the 
> add_maintainers.pl/get_maintainer.pl  file into a separate document under a 
> Xen specific development tools section and just refer to it
>     * Sending patches manually - we should nuke this section and focus on the 
> next section
>     * I would move the bulk of this into a Contribution Workflow section, 
> which gives an overall workflow and just highlight the reroll count. We 
> should define the tags and conventions such as RFC somewhere in an 
> introductory section of this document
>    * All the QEMU, Linux, ... stuff can either stay on the Wiki or could be 
> broken out
> * https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project - strip 
> all the XAPI stuff. NBot sure whether 
> https://wiki.xenproject.org/wiki/XenParavirtOpsHelp is still applicable: nuke 
> if not
> 
> Key content that is missing
> * An overview for testing, which should include
>    - OSSTEST
>    - XTF
>    - The GitLab CI
> * Outcome from the Minimum Standards and Best Practices discussion at 
> https://lists.xenproject.org/archives/html/xen-devel/2019-06/msg01518.html 
> depending on outcome. I was thinking about a Community Standards section, 
> which would point to a Code of Conduct/Minimum and Best Practices (maybe 
> written by role: aka contributor, reviewer and maybe committer)
> * Release Process Related documentation (from a contributor's perspective)
> * Maybe a description of the source tree
> * Some of the information in SUPPORT.md in a feature lifecycle document
> * Maybe some of the things people need to know about KCONFIG
> 
> Let me know what you think. I will start with some of the easier bits next 
> week if I can find some time, unless there are major objections.

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

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

etc.

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