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

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

On 17/10/2019, 18:05, "Rich Persaud" <persaur@xxxxxxxxx> wrote:

    On Oct 17, 2019, at 12:55, Stefano Stabellini <sstabellini@xxxxxxxxxx> 
wrote:
    > 
    > On Thu, 17 Oct 2019, Rich Persaud wrote:
    >>> On Oct 17, 2019, at 12:32, Stefano Stabellini <sstabellini@xxxxxxxxxx> 
wrote:
    >>> 
    >>> On Thu, 17 Oct 2019, Lars Kurth wrote:
    >>>> On 16/10/2019, 17:35, "Rich Persaud" <persaur@xxxxxxxxx> wrote:
    >>>> 
    >>>>>> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@xxxxxxxxx> 
wrote:
    >>>>> ...
    >>>>> 
    >>>>> My point really was is that due to storing the files in git, we 
essentially do NOT today do this.
    >>>>> So we would need to take extra action: e.g. manually or through 
tooling
    >>>>> 
    >>>>>>> 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
    >>>>>> 
    >>>>>> This is also helpful for provenance of changes, which is relevant in 
safety-oriented documentation.  It can be used to clearly delineate CC-licensed 
content (which may be reused by many companies) from "All Rights Reserved" 
commercial content that may be added for a specific commercial audience or 
purpose.
    >>>>> 
    >>>>> I agree
    >>>>> 
    >>>>> I think the outcome of this analysis is really that the only 
significant difference between BSD and CC-BY in this context is the  "All 
Rights Reserved" portion
    >>>> 
    >>>>   Also - BSD is a "software" license while CC-BY is a "content" 
license, so they are not strictly comparable, even if they use similar 
terminology.
    >>>> 
    >>>> True, but as we have noticed the boundary between content and in-code 
docs content is fuzzy.
    >>>> 
    >>>>>> There is a difference between "software" which "runs on machines" 
and "documentation" which "runs on humans".  Combined software (e.g. BSD code 
from two origins) is executed identically, despite origin.  Humans make value 
judgements based on the author/origin of content, hence the focus on 
attribution.  Yes, there is a provenance graph in git (software/data), but 
that's not typically visible to human readers, except as a generated report, 
i.e. documentation.
    >>>>> 
    >>>>> Yes true. But also true for CC-BY-4 sources stored in git unless 
extra action is taken 
    >>>>> 
    >>>>> But my point is: 
    >>>>> * If we take extra action as e.g. proposed in 4.2 we can apply this 
uniformly to BSD as well as CC-BY pages
    >>>>> * We can add a section on re-use as proposed in 4.2 which recommends 
best practices around 5.  
    >>>>> * We can highlight sections that are BSD vs CC-BY in such a section, 
such that someone who has issue can remove these easily
    >>>>> 
    >>>>> In addition to these points: maybe it is too impractical to create 
ABI documentation based on CC-BY-4 (given that a lot of what we need is already 
in BSD sources). 
    >>>>> We could just copy some of the content in the BSD sources to new 
CC-BY-4 sources, but in practice it would just be hiding the potential legal 
issues behind it. 
    >>>>> Someone could contest the creation and argue that portions of the now 
CC-BY-4 sources are in fact BSD: in practice this is extremely unlikely, but it 
is possible.
    >>>>> 
    >>>>>>> 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
    >>>>>> 
    >>>>>> If we don't want the incentives and provenance properties of CC-BY, 
there is the option of CC0, which is the equivalent of public domain.  This 
would delegate the task of separating commercial vs CC content to each reader, 
without any license-required attribution or separation.
    >>>>>> 
    >>>>>> Some background on licenses designed for documentation, which has 
different legal requirements than software:
    >>>>>> 
    >>>>>> https://www.dreamsongs.com/IHE/IHE-50.html
    >>>>>> https://creativecommons.org/faq/#what-are-creative-commons-licenses 
(not for s/w)
    >>>>> 
    >>>>> I will have a look. But the core issue - which is why I have proposed 
what I have - is the question on how practically ABI documentation published 
under CC-BY-4, when much of this information has already been published in the 
past as code under BSD.
    >>>> 
    >>>>   Is there a reference sample of:
    >>>> 
    >>>>   - previously published, BSD-licensed, ABI 
specification-as-source-code
    >>>> 
    >>>> All of http://xenbits.xen.org/docs/unstable/hypercall
    >>>> And some can be content rich as seen in 
http://xenbits.xen.org/docs/unstable/hypercall/arm/include,public,xen.h.html#Func_HYPERVISOR_mmu_update
    >>>> 
    >>>>   - the corresponding FuSA ABI documentation for that source file
    >>>> 
    >>>> We do NOT have ANY FuSA documentation at this stage. And there are NO 
examples of such docs in the public domain
    >>>> I am waiting for a sanitised smallish system software example to be 
made available, which should help us identify the practical implications 
    >>>> However, ABI documentation would be part of it
    >>>> 
    >>>>   If there is almost a 1:1 correspondence between ABI "docs" and 
"code", could the necessary FuSA annotations become part of the source code 
file, e.g. comments or tags?  Or is there a requirement for the ABI 
documentation to have a specific layout in a printable report?
    >>>> 
    >>>> I don’t think there will be a 1:1 mapping. The documentation would 
typically be
    >>>> - Interface docs (e.g. ABI docs) - there will likely be a clean 
mapping 
    >>>> - Requirements: specifying what the system is supposed to do - no 
clean mapping to source
    >>>> - Designs, Architecture docs, ... - no clean mapping to source
    >>>> - Test Specs - should have clean mapping to test code, but not to 
tested code
    >>>> 
    >>>> We do still need some sort of tagging for tracability
    >>>> 
    >>>> In any case: I think we are at the stage where we need to hear from 
Andy and others
    >>> 
    >>> Just to make my thinking clear: I don't care very much about the
    >>> specific license, and if we have options, it looks like one of Creative
    >>> Commons would probably be my favorite.
    >>> 
    >>> My only requirement is that we can copy/paste comments between headers
    >>> files and docs in both directions. As long as we can do that, the
    >>> license is fine by me.  Given that the headers files are BSD, it looks
    >>> like the best way to achieve compatibility is using BSD for the docs
    >>> too.
    >>> 
    >>> However, if you tell me that we can copy/paste sentences between BSD
    >>> headers, Creative Commons docs, and back, then I am also fine with that.
    >> 
    >> As both doc and code maintainers can attest, duplication of text between 
code and docs will inevitably lead to divergence.  A document, e.g. a book, can 
include the printed and unmodified text of source code under the rights granted 
by a source code license.  With line numbers for that printed source code, the 
document can cite references to the source code.
    >> 
    >> Unless there is a specific formal requirement in FuSA documentation for 
intermingling documentation and source code on the same digital or printed 
"page" layout, they can be separated within the document and subjected to 
different licenses.  
    >> 
    >> If there is a specific legal FuSA requirement for text layout of code 
and docs, it would be good to see the legal text which defines the text layout 
requirement.
    > 
    > My request comes from experience working on code, comments, commit
    > messages, and docs. It is common to move sentences across between all of
    > them. Note that I said "move" not "copy". It might start as a comment,
    > then being moved to the docs. Or, it could start as a design doc, and we
    > might want to move the more technical details closer to the code as
    > comments. I don't think we should put ourselves in a position where this
    > is impossible to do because of licensing issues, if we have a choice.
    > 
    > If we have to weight the advantage of using CC for docs, losing the
    > chance of moving sentences back and forth, against using BSD for docs
    > with the ability of moving sentences back and forth, then CC needs to
    > have very significance advantages to make it worth it, or being required
    > for other reasons.
    
    CC0 (public domain) has less restrictions than BSD, but the former is a 
license for documentation and the latter is a license for source code. 
    
    Before we ask Xen FuSA contributors to invest in documentation to be 
presented as legally-valid evidence for certification, we should ask a 
certified lawyer for their formal opinion on the validity of:
    
      (a) applying a source code license (BSD) to documentation

There are also BSD documentation license variants which may be worth looking at

      (b) moving text bidirectionally between source code (BSD) and 
documentation (any license)
      (c) moving text bidirectionally between source code (BSD) and 
documentation (CC0)
    
I will raise this at the next SIG meeting
I can also ask the LF for advice: it would be from a certified lawyer, but 
informal, as legal LF staff cannot provide formal advice to projects
For formal advice, we have to open the project's cheque book

Regards
Lars

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