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

[Rich Persaud <persaur@xxxxxxxxx>]

> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@xxxxxxxxx> wrote:
> Hi Rich,
> 
>>>> On 15 Oct 2019, at 02:58, Rich Persaud <persaur@xxxxxxxxx> wrote:
>>>>> On Oct 11, 2019, at 07:11, Lars Kurth <lars.kurth@xxxxxxxxxx> wrote:
>>> On 11/10/2019, 02:24, "Stefano Stabellini" <sstabellini@xxxxxxxxxx> wrote:
>>>>   On Thu, 10 Oct 2019, Lars Kurth wrote:
>>>> @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
>> 
>> This is equivalent to attribution of the copyright owner of the originally 
>> created file.
>> 
>>> Does *not* have requirements around attribution as CC-BY-4: however,
>>> as we store everything in git attribution is handled by us by default
>> 
>> See above, the license header attributes copyright, since BSD was created 
>> for "software" and people who work on "software" would typically be looking 
>> at source code, hence the primary attribution takes place there, with 
>> secondary attribution in EULAs, "About" panels, etc.
>> 
>>> 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
>> 
>> One motivation for CC-BY (with attribution) is to create an incentive 
>> (credit) for the creation of documentation, which is not commonly a favorite 
>> pastime of developers.   Credit typically goes at least to the original 
>> author of a section of documentation, with varying ways of crediting 
>> subsequent contributors.  The documentation can be structured to make 
>> crediting easier.  The mechanism for crediting can be designed to encourage 
>> specific outcomes, along our projected doc lifecycle for safety 
>> certification, contributors, evaluators and commercial investors.
> 
> 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.

>> 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
- the corresponding FuSA ABI documentation for that source file

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?

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