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

[Lars Kurth <lars.kurth.xen@xxxxxxxxx>]

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

> 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.

Regards
Lars


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