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

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

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

Regards
Lars

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