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

[Artem Mygaiev <Artem_Mygaiev@xxxxxxxx>]

Hi Lars

On Thu, 2019-10-17 at 17:30 +0000, Lars Kurth wrote:
> 
> 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://urldefense.com/v3/__https://www.dreamsongs.com/IHE/IHE-50.html__;!K6dmGCEab4ueJg!kzVGzaxQSxR-63kIKCKdKg9tpj03tZTi7-WJQ4Jv0YsIdRVLFr8VUmElp-msVq7CLg$
>  
>     >>>>>> 
> https://urldefense.com/v3/__https://creativecommons.org/faq/*what-are-creative-commons-licenses__;Iw!K6dmGCEab4ueJg!kzVGzaxQSxR-63kIKCKdKg9tpj03tZTi7-WJQ4Jv0YsIdRVLFr8VUmElp-lzx1cSwA$
>   (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 
> https://urldefense.com/v3/__http://xenbits.xen.org/docs/unstable/hypercall__;!K6dmGCEab4ueJg!kzVGzaxQSxR-63kIKCKdKg9tpj03tZTi7-WJQ4Jv0YsIdRVLFr8VUmElp-nFc5YH-w$
>  
>     >>>> And some can be content rich as seen in 
> https://urldefense.com/v3/__http://xenbits.xen.org/docs/unstable/hypercall/arm/include,public,xen.h.html*Func_HYPERVISOR_mmu_update__;Iw!K6dmGCEab4ueJg!kzVGzaxQSxR-63kIKCKdKg9tpj03tZTi7-WJQ4Jv0YsIdRVLFr8VUmElp-kPPrMccA$
>  
>     >>>> 
>     >>>>   - 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 think it has nothing to do with safety, the topic is very generic
(unless you mean funding this work)

> 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

That'd be great, there are multiple examples when pieces of code were
copied from e.g. LK to some book or other document. IMHO there shall be
someone in LF who is familiar with the matter. BTW maybe worth asking
@ELISA call? They have similar if not the same issues on documentation

> 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