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

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

On 11/10/2019, 02:24, "Stefano Stabellini" <sstabellini@xxxxxxxxxx> wrote:

    On Thu, 10 Oct 2019, Lars Kurth wrote:
    > * 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
    
    Hi Lars,
    
    Thanks for putting this email together.
    
    In terms of formats, I don't have a preference between rst and pandoc,
    but if we are going to use rst going forward, I'd say to try to use rst
    for everything, including converting all the old stuff. The fewer
    different formats, the better.

I think the proposal that needs to follow on from this (which would at some
point need to be voted on) would then be to go for rst. 
    
    As I mentioned during the FuSa call, I agree with you, Andrew, and
    others that it would be best to have the docs under a CC license. I do
    expect that we'll end up copy/pasting snippets of in-code comments into
    the docs, so I think it is important that we are allowed to do that from
    a license perspective. It is great that GPLv2 allows it (we need to be
    sure about this).

The GPL does *not* allow this, but (c) law and fair use clauses do. So typically
stuff such as
* Referring to function names, signatures, etc. tend to be all fine
* Copying large portions of in-line comments would not be fine, but
If they are large, they would in most cases be re-written in a more suitable
language. 

So, I think overall, we should be fine. It's a bit of a grey area though.

And as you point out below, most of the code in question is typically BSD 
    
    Yes, I expect that some docs might be automatically generated, but from
    header files, not from source code. Especailly public/ header files,
    which are typically BSD, not GPLv2. I cannot come up with examples of
    docs we need to generated from GPLv2-only code at the moment, hopefully
    there won't be any.
    
That makes things a lot easier.    
         
    >     I wasn't planning on reusing any of the markup, and wasn't expecting 
to
    >     use much of the text either.  I'm still considering the option of
    >     defining that xen/public/* isn't the canonical description of the ABI,
    >     because C is the wrong tool for the job.
    >     
    >     Its fine to provide a C set of headers implementing an ABI, but there 
is
    >     a very deliberate reason why the canonical migration v2 spec is in a
    >     text document.
    > 
    > @Stefano: as you and I believe Brian will be spending time on improving 
the
    > ABI docs, I think we need to build some agreement here on what/how
    > to do it. I was assuming that generally the consensus was to have
    > docs close to the code in source, but this does not seem to be the case.
    > 
    > But if we do have stuff separately, ideally we would have a tool that 
helps
    > point people editing headers to also look at the relevant docs. Otherwise 
it will
    > be hard to keep them in sync.
    
    In general, it is a good idea to keep the docs close to the code to make
    it easier to keep them up to date. But there is no one-size-fits-all
    here. For public ABI descriptions, I agree with Andrew that ideally they
    should not be defined as C header files.
    
    But it is not an issue: any work that we do here won't be wasted. For
    instance, we could start by adding more comments to the current header
    files. Then, as a second step, take all the comments and turn them into
    a proper ABI description document without any C function declarations.
    It is easy to move English text around, as long as the license allows it
    -- that is the only potential blocker I can see.

This is likely to be problematic. First of all, we are talking about 
BSD-3-Clause
or BSD-2-Clause code (the latter is more dominant in headers I believe) in
all known cases.

The main properties of the BSD are
1: Can be pretty much used anywhere for any purpose
2: Can be modified for any purpose 
3: But the original license header must be retained in derivates

Does *not* have requirements around attribution as CC-BY-4: however,
as we store everything in git attribution is handled by us by default

CC-BY-4 also has properties 1-3
In addition: it does require that 
4: Derived works are giving appropriate credit to authors 
    We could clarify in a COPYING how we prefer to do this
    4.1: We could say that "referring to the Xen Project community" 
            is sufficient to comply with the attribution clause
    4.2: We could require individual authors to be credited: in that
            case we probably ought to lead by example and list the authors
            in a credit/license section and extract the information from
            git logs when we generate it (at some point in the future)
5: You give an indication whether you made changes ... in practice
this means you have to state significant changes made to the works

As such, BSD-2/3-Clause in our context works similarly to CC-BY-4
from a downstream's perspective. In fact CC-BY-4 is somewhat stricter

This seems to say to me that the most pragmatic way forward is to create 
these new ABI documents under BSD-2/3-Clause and accept that the
produced work is not fully CC-BY-4 (but in all practical terms behaves
as if it were). The only downside I can see is a slightly less pure
COPYING, README or credit/license section in the generated document
but for practical use there is no actual difference.

@Andy: as you have maybe a stronger view on this, it would be good
to get your view

Best Regards
Lars
 




    

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