Re: [Xen-devel] [PATCH 1/4] docs/sphinx: License content with CC-BY-4.0

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

On 07/10/2019, 13:29, "Andrew Cooper" <Andrew.Cooper3@xxxxxxxxxx> wrote:

    On 07/10/2019 13:01, Lars Kurth wrote:
    >
    > On 03/10/2019, 21:56, "Andrew Cooper" <andrew.cooper3@xxxxxxxxxx> wrote:
    >
    >     Creative Commons is a more common license than GPL for documentation 
purposes.
    >     Switch to using CC-BY-4.0 to explicitly permit re-purposing and 
remixing of
    >     the content.
    >     
    >     Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
    >     ---
    >     CC: Lars Kurth <lars.kurth@xxxxxxxxxx>
    >     CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx>
    >     CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
    >     CC: Jan Beulich <JBeulich@xxxxxxxx>
    >     CC: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>
    >     CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
    >     CC: Tim Deegan <tim@xxxxxxx>
    >     CC: Wei Liu <wl@xxxxxxx>
    >     CC: Julien Grall <julien@xxxxxxx>
    >     CC: Rich Persaud <persaur@xxxxxxxxx>
    >     CC: Juergen Gross <jgross@xxxxxxxx>
    >     ---
    >      COPYING                                 |  3 +++
    >      docs/README.source                      | 32 
++++++++++++++++++++++++++++++++
    >      docs/admin-guide/index.rst              |  2 ++
    >      docs/admin-guide/microcode-loading.rst  |  2 ++
    >      docs/conf.py                            |  1 +
    >      docs/guest-guide/index.rst              |  2 ++
    >      docs/guest-guide/x86/hypercall-abi.rst  |  2 ++
    >      docs/guest-guide/x86/index.rst          |  2 ++
    >      docs/hypervisor-guide/code-coverage.rst |  2 ++
    >      docs/hypervisor-guide/index.rst         |  2 ++
    >      docs/index.rst                          |  2 ++
    >      11 files changed, 52 insertions(+)
    >      create mode 100644 docs/README.source
    >     
    >     diff --git a/COPYING b/COPYING
    >     index 310fd52c27..80fac091d3 100644
    >     --- a/COPYING
    >     +++ b/COPYING
    >     @@ -47,6 +47,9 @@ various drivers, support functions and header files 
within Xen-aware
    >      Linux source trees. In all such cases, license terms are stated at 
the
    >      top of the file or in a COPYING file in the same directory.
    >      
    >     +Sphinx documentation is licensed under CC-BY 4.0.  See
    >     +docs/README.source for more specific information.
    >     +
    >      In some cases, compatible 3rd party code has been imported into the
    >      Xen tree, retaining the original license, such as
    >        - AES-128 3.0
    >     diff --git a/docs/README.source b/docs/README.source
    >     new file mode 100644
    >     index 0000000000..f20fa92c28
    >     --- /dev/null
    >     +++ b/docs/README.source
    >     @@ -0,0 +1,32 @@
    >     +Sphinx documentation:
    >     +
    >     +All source rendered by Sphinx is licensed under CC-BY-4.0.
    >
    > Sorry for opening this can of worms. 
    >
    > Although I had seen the discussion between Rich and you about this, I had 
    > not actually done any groundwork on the licensing. 
    >
    > So, we have to look at two things:
    >
    > * Compatibility:
    >    See 
https://creativecommons.org/2015/10/08/cc-by-sa-4-0-now-one-way-compatible-with-gplv3/
 
    >    This makes CC-BY-4.0 inbound compatible with GPLv3
    >    It's not clear to me whether GPLv2 is compatible with CC-BY 4.0: lack 
of publicly
    >    available information implies this is not the case 
    >
    > * Output License
    >    But even if it is, the produced sphinx output would be GPLv2, not 
CC-BY 4.0
    >    This would even be true if none of the older GPLv2 docs portions were 
included, as
    >    the API docs generated from source are GPLv2
    >
    > As such the statement "All source rendered by Sphinx is licensed under
    > CC-BY-4.0" is wrong.
    
    At the moment, I (and therefore Citrix in practice) holds the copyright
    on all rst content which exists in Xen.
    
    The point of this patch is to get it licensed sensibly (and in
    particular, not falling back to the GPL default) before 4.13 goes out of
    the door.
    
    The result therefore is uniformly CC-BY-4.0, with no GPL in sight.

Having looked at this again, you are correct. I was assuming that 
https://andrewcoop-xen.readthedocs.io/en/docs-devel/guest-guide/x86/hypercall-abi.html
was linking to the doxygen generated ABI docs, which it seems not to do.
    
    > Although it is probably correct to say "All CC-BY 4.0 source rendered by
    > Sphinx is licensed under CC-BY-4.0", because Sphinx retains the source 
file
    > to html mapping and linkage in docs generation works differently
    > to linkage in code. 
    >
    > I am wondering whether anyone else has come across this. This question in
    > particular goes back to Rich who made a very strong case for CC-BY-4.0 
based
    > documentation. I don't think we would have an issue if the entire sphinx 
doc-set
    > is GPLv2 if most content is licensed under CC-BY-4.0, except that such an
    > approach would make re-using the entire sphinx generated docset messy.
    >
    > We probably also want to maintain the capability to copy text from some
    > documentation freely into the source tree and vice versa, if needed. This 
is
    > particularly true for content in Technical Debt, user content (may end up 
in
    > man pages), etc.
    
    I disagree, insofar as blindly copying notes out of source code and into
    the sphinx documentation is liable to get a -1 from me.

I was actually looking at this the other way round: let's say we have
good information in a section about Technical Debt in the sphinx docs
and some of it may end up in the tree, then we could have an issue.
The dual license approach would enable us to do this.
    
    The types of style/language which are appropriate for these two cases
    are a disjoint set.

I think we are agreed. 
    
    >
    > Maybe the right approach would be to dually license the documentation
    > files using both GPLv2 and CC-BY 4.0 and quantifying this in the COPYING
    > file of the docs directory (starting from a specific date). We could 
eventually
    > re-license all the other stuff over time, which should be relatively 
straightforward
    > and/or exclude specific problematic directories.
    
    I don't see how that helps for blindly copying things in.  They'd still
    be GPL2 strictly, and would need explicit relicensing to become dual
    licensed, at which point, why not go straight for consistency?

It doesn't help with this case: it does help with copying information from the
sphinx docs to the tree 

I think we need to have a discussion/proposal after this series is committed 
covering
topics such as
* File formats for say man pages (or other docs)
* What are the acceptable use-cases of copying information from existing 
documentation to sphinx docs
   - Copying information from the Wiki to sphinx: the Wiki is CC-BY 3.0 and 
forward compatible, while (c) are retained - we should be OK
   - Would we want to link to man pages from the sphinx docset
   - Would we want to link to ABI docs generated from the sphinx docset in 
future
* What type of content may end up in a GPLv2 code with the sphinx docs as source

What this says to me is that we probably need to put a bit more thought into 
this

However, you have convinced me, that this does not have to happen before 4.13 
as long as we make sure we can still change licensing if we need to after 4.13
is released.    

I think we need to have a wider discussion about this set of topics
as use-case, format and license are potentially entangled for what we may
want to do in future. I can run with this: I already promised to cover the man 
page format portion and can cast the net a bit more widely

    >
    > Things like standardising say man pages to rst, would potentially also
    > create complexities with this patch, because of 
    >     +This includes:
    >     +  * All ReStructured Text files:          docs/*/*.rst
    >
    > I don't want this to become a long-winded conversation during the 4.13 
freeze.
    > Please keep this in mind when responding.
    >
    > It may mean though, that we can't resolve this before 4.13 is released
    
    Getting this fixed is a blocker for 4.13.
    
I think you have shown that my concern was not valid for this particular
patch at this time. 

Note that my aim is NOT to blindly copy notes out of source code and into
the sphinx documentation. But I would like to end up in a position where
contributors to docs do not have to think about licensing nor have to deal
with a plethora of different file formats. I am however worried that we
end up with something fragile and complex, creating barriers that are
unnecessary unless we give this some more thought.

Regards
Lars




    

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