[Xen-devel] [RFC] Documentation formats, licenses and file system structure

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

Hi all,

following on from a discussion on IRC and on various other places, I think we 
need to try and rationalize how we handle documentation.

What we have now and what we may get in future
* http://xenbits.xen.org/docs/unstable/ (GPL-2)
* http://xenbits.xen.org/docs/sphinx-unstable-staging/ (CC-BY-4)
* Additional API documentation (with a view to enabling safety) 
* Any future documentation related to safety (requirements, designs, test 
cases, tracability)

Desired licenses
* There is a desire to keep 
http://xenbits.xen.org/docs/sphinx-unstable-staging/ CC-BY-4 only
* There is a desire to publish future documentation related to safety as CC-BY-4

Existing formats and licenses
* Hypercall ABI Documentation generated from Xen public headers
Format: kerndoc
License: typically BSD-3-Clause (documentation is generated from public headers)
* docs/designs, docs/features, docs/specs
Formats: primarily pandoc, with some files md
License: GPL-2
* docs/processs - covers internal processes
Formats: txt, with some pandoc
License: GPL-2
* docs/figs
Formats: misc
License: GPL-2
* docs/misc
Formats: txt, with some large number of pandoc, some other docs
License: GPL-2
* docs/man
Formats: pod
License: GPL-2
* Sphinx docs: docs, docs/guest-guide, docs/hypervisor-guide
Formats: rst
License: CC-BY-4

* Wiki: 
Formats: mediawiki markdown
License: CC-BY-SA-3 which has an automatic update to CC-BY-SA-4
(c) of Wiki contributions are kept by the authors

This means that the 3 most common file formats in use are
* pod
* pandoc (with some md) - these are essentially identical
* txt for legacy and old stuff
* rst

License compatibility
* GPL-2 and CC-BY-4 are compatible, but mixing means that the complete docset 
is GPL-2
* GPL-2 and BSD-3-Clause are compatible, but mixing means that the complete 
docset is GPL-2
* BSD-3-Clause and CC-BY-4 I am not 100% sure, but should not be an issue
* CC-BY-SA-4 is only one way compatible with GPLv3 (affecting content on the 
wiki)

The first question is whether we should convert pod to rst
* https://metacpan.org/pod/pod2rst provides a conversion tool
* man pages can be generated by rst2man
Thus, technically this should be easy and should make contributions to docs/man 
easier
If we do this, we should add a CONTRIBUTING file, clarifying the license in 
this directory

There are a set of related questions on what we would eventually merge into the 
sphinx
docset. I believe there is agreement that most of what is in docs today is not 
really
suitable, however there are a few possible exceptions
* man pages - with a variety of different contributors from different orgs. 
Changing license would be hard 
* API docs generated from PUBLIC headers - changing license would be 
impossible, but would be BSD-3-Clause
* Some wiki content (e.g. 
https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches and friends) 
   More than 95% of changes were from Citrix staff, so we could convert to 
CC-BY-4
   Most non-Citrix changes are one-line changes and could be covered by fair use
* Possibly stuff such as 
https://xenbits.xen.org/docs/unstable/support-matrix.html (which is currently 
GPL-2,
   but we could relicense to say GPL-2 and CC-BY-4 if we had to)
The implication is that the sphinx docs would not be fully CC-BY-4, but the 
bulk of the pages would be

* Would we ever include API docs generated from GPLv2 code? E.g. for safety 
use-cases?
@Stefano, @Artem: I guess this one is for you. 
I suppose if we would have a similar issue for a safety manual
I am also assuming we would want to use sphinx docs and rst to generate a 
future safety manual

Other pages in docs that may be useful for the sphinx docs should essentially 
be re-written, 
so we would be fine from a licensing perspective. That means that over time, we 
could get rid of 
pandoc and text files in docs/misc, docs/designs, docs/features, docs/specs 
which
have not really built a lot of traction.

Related to this is the general question, whether we would ever copy code from 
source to docs
and vice versa and to which degree. This is an unknown to me: I think in 
practice we have not seen
much or even any of this in the past.

On licensing, we should try and make the docs directory clean, e.g.
* We should set the default to CC-BY-4 (e.g. through a contributing file in 
docs)
* And specifically use GPL-2 for directories such as docs/misc, docs/man, ...

In any case, this seems all a little bit of a mess at the moment and I think we 
need to
agree on a foundation to get us to a better state. This mail is a start and 
intends to gather
input and will eventually lead to a more concrete proposal.

If I have missed anything, feel free to add

Best Regards
Lars



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