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

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

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.

Best Regards
Lars  

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