* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-11 11:09 ` Lars Kurth
@ 2019-10-11 17:33 ` Stefano Stabellini
2019-10-15 1:56 ` P S
2019-10-15 1:58 ` Rich Persaud
2 siblings, 0 replies; 23+ messages in thread
From: Stefano Stabellini @ 2019-10-11 17:33 UTC (permalink / raw)
To: Lars Kurth
Cc: Artem Mygaiev, Stefano Stabellini, Andrew Cooper, Rich Persaud,
Committers, xen-devel
[-- Attachment #1: Type: text/plain, Size: 6102 bytes --]
On Fri, 11 Oct 2019, Lars Kurth wrote:
> On 11/10/2019, 02:24, "Stefano Stabellini" <sstabellini@kernel.org> wrote:
>
> On Thu, 10 Oct 2019, Lars Kurth wrote:
> > * Would we ever include API docs generated from GPLv2 code? E.g. for safety use-cases?
> > @Stefano, @Artem: I guess this one is for you.
> > I suppose if we would have a similar issue for a safety manual
> > I am also assuming we would want to use sphinx docs and rst to generate a future safety manual
>
> Hi Lars,
>
> Thanks for putting this email together.
>
> In terms of formats, I don't have a preference between rst and pandoc,
> but if we are going to use rst going forward, I'd say to try to use rst
> for everything, including converting all the old stuff. The fewer
> different formats, the better.
>
> I think the proposal that needs to follow on from this (which would at some
> point need to be voted on) would then be to go for rst.
>
> As I mentioned during the FuSa call, I agree with you, Andrew, and
> others that it would be best to have the docs under a CC license. I do
> expect that we'll end up copy/pasting snippets of in-code comments into
> the docs, so I think it is important that we are allowed to do that from
> a license perspective. It is great that GPLv2 allows it (we need to be
> sure about this).
>
> The GPL does *not* allow this, but (c) law and fair use clauses do. So typically
> stuff such as
> * Referring to function names, signatures, etc. tend to be all fine
> * Copying large portions of in-line comments would not be fine, but
> If they are large, they would in most cases be re-written in a more suitable
> language.
>
> So, I think overall, we should be fine. It's a bit of a grey area though.
>
> And as you point out below, most of the code in question is typically BSD
>
> Yes, I expect that some docs might be automatically generated, but from
> header files, not from source code. Especailly public/ header files,
> which are typically BSD, not GPLv2. I cannot come up with examples of
> docs we need to generated from GPLv2-only code at the moment, hopefully
> there won't be any.
>
> That makes things a lot easier.
>
> > I wasn't planning on reusing any of the markup, and wasn't expecting to
> > use much of the text either. I'm still considering the option of
> > defining that xen/public/* isn't the canonical description of the ABI,
> > because C is the wrong tool for the job.
> >
> > Its fine to provide a C set of headers implementing an ABI, but there is
> > a very deliberate reason why the canonical migration v2 spec is in a
> > text document.
> >
> > @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
>
> Does *not* have requirements around attribution as CC-BY-4: however,
> as we store everything in git attribution is handled by us by default
>
> 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
> 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
>
> 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
>
> This seems to say to me that the most pragmatic way forward is to create
> these new ABI documents under BSD-2/3-Clause and accept that the
> produced work is not fully CC-BY-4 (but in all practical terms behaves
> as if it were). The only downside I can see is a slightly less pure
> COPYING, README or credit/license section in the generated document
> but for practical use there is no actual difference.
FWIW I am OK with this. In fact, I think it is a good idea because it
does look like that it will make comments and text easier to move
around, which far overcome the small downside.
[-- Attachment #2: Type: text/plain, Size: 157 bytes --]
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-11 11:09 ` Lars Kurth
2019-10-11 17:33 ` Stefano Stabellini
@ 2019-10-15 1:56 ` P S
2019-10-15 1:58 ` Rich Persaud
2 siblings, 0 replies; 23+ messages in thread
From: P S @ 2019-10-15 1:56 UTC (permalink / raw)
To: Lars Kurth
Cc: Artem Mygaiev, Stefano Stabellini, Andrew Cooper, Rich Persaud,
Committers, xen-devel
[-- Attachment #1.1: Type: text/plain, Size: 7690 bytes --]
On Oct 11, 2019, at 07:11, Lars Kurth <lars.kurth@citrix.com> wrote:
>
> On 11/10/2019, 02:24, "Stefano Stabellini" <sstabellini@kernel.org> wrote:
>
>> On Thu, 10 Oct 2019, Lars Kurth wrote:
>> * Would we ever include API docs generated from GPLv2 code? E.g. for safety use-cases?
>> @Stefano, @Artem: I guess this one is for you.
>> I suppose if we would have a similar issue for a safety manual
>> I am also assuming we would want to use sphinx docs and rst to generate a future safety manual
>
> Hi Lars,
>
> Thanks for putting this email together.
>
> In terms of formats, I don't have a preference between rst and pandoc,
> but if we are going to use rst going forward, I'd say to try to use rst
> for everything, including converting all the old stuff. The fewer
> different formats, the better.
>
> I think the proposal that needs to follow on from this (which would at some
> point need to be voted on) would then be to go for rst.
>
> As I mentioned during the FuSa call, I agree with you, Andrew, and
> others that it would be best to have the docs under a CC license. I do
> expect that we'll end up copy/pasting snippets of in-code comments into
> the docs, so I think it is important that we are allowed to do that from
> a license perspective. It is great that GPLv2 allows it (we need to be
> sure about this).
>
> The GPL does *not* allow this, but (c) law and fair use clauses do. So typically
> stuff such as
> * Referring to function names, signatures, etc. tend to be all fine
> * Copying large portions of in-line comments would not be fine, but
> If they are large, they would in most cases be re-written in a more suitable
> language.
>
> So, I think overall, we should be fine. It's a bit of a grey area though.
>
> And as you point out below, most of the code in question is typically BSD
>
> Yes, I expect that some docs might be automatically generated, but from
> header files, not from source code. Especailly public/ header files,
> which are typically BSD, not GPLv2. I cannot come up with examples of
> docs we need to generated from GPLv2-only code at the moment, hopefully
> there won't be any.
>
> That makes things a lot easier.
>
>> I wasn't planning on reusing any of the markup, and wasn't expecting to
>> use much of the text either. I'm still considering the option of
>> defining that xen/public/* isn't the canonical description of the ABI,
>> because C is the wrong tool for the job.
>>
>> Its fine to provide a C set of headers implementing an ABI, but there is
>> a very deliberate reason why the canonical migration v2 spec is in a
>> text document.
>>
>> @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.
> 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.
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.
> 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)
Rich
[-- Attachment #1.2: Type: text/html, Size: 11586 bytes --]
[-- Attachment #2: Type: text/plain, Size: 157 bytes --]
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-11 11:09 ` Lars Kurth
2019-10-11 17:33 ` Stefano Stabellini
2019-10-15 1:56 ` P S
@ 2019-10-15 1:58 ` Rich Persaud
2019-10-15 12:25 ` Lars Kurth
2 siblings, 1 reply; 23+ messages in thread
From: Rich Persaud @ 2019-10-15 1:58 UTC (permalink / raw)
To: Lars Kurth
Cc: Artem Mygaiev, Stefano Stabellini, Andrew Cooper, Rich Persaud,
Committers, xen-devel
[-- Attachment #1.1: Type: text/plain, Size: 7692 bytes --]
> On Oct 11, 2019, at 07:11, Lars Kurth <lars.kurth@citrix.com> wrote:
>
> On 11/10/2019, 02:24, "Stefano Stabellini" <sstabellini@kernel.org> wrote:
>
>> On Thu, 10 Oct 2019, Lars Kurth wrote:
>> * Would we ever include API docs generated from GPLv2 code? E.g. for safety use-cases?
>> @Stefano, @Artem: I guess this one is for you.
>> I suppose if we would have a similar issue for a safety manual
>> I am also assuming we would want to use sphinx docs and rst to generate a future safety manual
>
> Hi Lars,
>
> Thanks for putting this email together.
>
> In terms of formats, I don't have a preference between rst and pandoc,
> but if we are going to use rst going forward, I'd say to try to use rst
> for everything, including converting all the old stuff. The fewer
> different formats, the better.
>
> I think the proposal that needs to follow on from this (which would at some
> point need to be voted on) would then be to go for rst.
>
> As I mentioned during the FuSa call, I agree with you, Andrew, and
> others that it would be best to have the docs under a CC license. I do
> expect that we'll end up copy/pasting snippets of in-code comments into
> the docs, so I think it is important that we are allowed to do that from
> a license perspective. It is great that GPLv2 allows it (we need to be
> sure about this).
>
> The GPL does *not* allow this, but (c) law and fair use clauses do. So typically
> stuff such as
> * Referring to function names, signatures, etc. tend to be all fine
> * Copying large portions of in-line comments would not be fine, but
> If they are large, they would in most cases be re-written in a more suitable
> language.
>
> So, I think overall, we should be fine. It's a bit of a grey area though.
>
> And as you point out below, most of the code in question is typically BSD
>
> Yes, I expect that some docs might be automatically generated, but from
> header files, not from source code. Especailly public/ header files,
> which are typically BSD, not GPLv2. I cannot come up with examples of
> docs we need to generated from GPLv2-only code at the moment, hopefully
> there won't be any.
>
> That makes things a lot easier.
>
>> I wasn't planning on reusing any of the markup, and wasn't expecting to
>> use much of the text either. I'm still considering the option of
>> defining that xen/public/* isn't the canonical description of the ABI,
>> because C is the wrong tool for the job.
>>
>> Its fine to provide a C set of headers implementing an ABI, but there is
>> a very deliberate reason why the canonical migration v2 spec is in a
>> text document.
>>
>> @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.
> 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.
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.
> 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)
Rich
[-- Attachment #1.2: Type: text/html, Size: 12482 bytes --]
[-- Attachment #2: Type: text/plain, Size: 157 bytes --]
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-15 1:58 ` Rich Persaud
@ 2019-10-15 12:25 ` Lars Kurth
2019-10-16 16:34 ` Rich Persaud
0 siblings, 1 reply; 23+ messages in thread
From: Lars Kurth @ 2019-10-15 12:25 UTC (permalink / raw)
To: Rich Persaud
Cc: Artem Mygaiev, Lars Kurth, Stefano Stabellini, Andrew Cooper,
Committers, xen-devel
Hi Rich,
> On 15 Oct 2019, at 02:58, Rich Persaud <persaur@gmail.com> wrote:
>
>> On Oct 11, 2019, at 07:11, Lars Kurth <lars.kurth@citrix.com> wrote:
>>
>> On 11/10/2019, 02:24, "Stefano Stabellini" <sstabellini@kernel.org> 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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-15 12:25 ` Lars Kurth
@ 2019-10-16 16:34 ` Rich Persaud
2019-10-17 13:24 ` Lars Kurth
0 siblings, 1 reply; 23+ messages in thread
From: Rich Persaud @ 2019-10-16 16:34 UTC (permalink / raw)
To: Lars Kurth
Cc: Artem Mygaiev, Lars Kurth, Stefano Stabellini, Andrew Cooper,
Committers, xen-devel
> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@gmail.com> wrote:
> Hi Rich,
>
>>>> On 15 Oct 2019, at 02:58, Rich Persaud <persaur@gmail.com> wrote:
>>>>> On Oct 11, 2019, at 07:11, Lars Kurth <lars.kurth@citrix.com> wrote:
>>> On 11/10/2019, 02:24, "Stefano Stabellini" <sstabellini@kernel.org> 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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-16 16:34 ` Rich Persaud
@ 2019-10-17 13:24 ` Lars Kurth
2019-10-17 16:32 ` Stefano Stabellini
0 siblings, 1 reply; 23+ messages in thread
From: Lars Kurth @ 2019-10-17 13:24 UTC (permalink / raw)
To: Rich Persaud, Lars Kurth
Cc: Artem Mygaiev, Andrew Cooper, Stefano Stabellini, Committers, xen-devel
On 16/10/2019, 17:35, "Rich Persaud" <persaur@gmail.com> wrote:
> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@gmail.com> 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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-17 13:24 ` Lars Kurth
@ 2019-10-17 16:32 ` Stefano Stabellini
2019-10-17 16:41 ` Rich Persaud
0 siblings, 1 reply; 23+ messages in thread
From: Stefano Stabellini @ 2019-10-17 16:32 UTC (permalink / raw)
To: Lars Kurth
Cc: Artem Mygaiev, Stefano Stabellini, Lars Kurth, Andrew Cooper,
Rich Persaud, Committers, xen-devel
[-- Attachment #1: Type: text/plain, Size: 6322 bytes --]
On Thu, 17 Oct 2019, Lars Kurth wrote:
> On 16/10/2019, 17:35, "Rich Persaud" <persaur@gmail.com> wrote:
>
> > On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@gmail.com> 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.
[-- Attachment #2: Type: text/plain, Size: 157 bytes --]
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-17 16:32 ` Stefano Stabellini
@ 2019-10-17 16:41 ` Rich Persaud
2019-10-17 16:53 ` Stefano Stabellini
0 siblings, 1 reply; 23+ messages in thread
From: Rich Persaud @ 2019-10-17 16:41 UTC (permalink / raw)
To: Stefano Stabellini
Cc: Artem Mygaiev, Lars Kurth, Lars Kurth, Andrew Cooper, Committers,
xen-devel
On Oct 17, 2019, at 12:32, Stefano Stabellini <sstabellini@kernel.org> wrote:
>
> On Thu, 17 Oct 2019, Lars Kurth wrote:
>> On 16/10/2019, 17:35, "Rich Persaud" <persaur@gmail.com> wrote:
>>
>>>> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@gmail.com> 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.
Rich
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-17 16:41 ` Rich Persaud
@ 2019-10-17 16:53 ` Stefano Stabellini
2019-10-17 17:05 ` Rich Persaud
0 siblings, 1 reply; 23+ messages in thread
From: Stefano Stabellini @ 2019-10-17 16:53 UTC (permalink / raw)
To: Rich Persaud
Cc: Artem Mygaiev, Lars Kurth, Stefano Stabellini, Lars Kurth,
Andrew Cooper, Committers, xen-devel
[-- Attachment #1: Type: text/plain, Size: 8070 bytes --]
On Thu, 17 Oct 2019, Rich Persaud wrote:
> On Oct 17, 2019, at 12:32, Stefano Stabellini <sstabellini@kernel.org> wrote:
> >
> > On Thu, 17 Oct 2019, Lars Kurth wrote:
> >> On 16/10/2019, 17:35, "Rich Persaud" <persaur@gmail.com> wrote:
> >>
> >>>> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@gmail.com> 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.
[-- Attachment #2: Type: text/plain, Size: 157 bytes --]
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-17 16:53 ` Stefano Stabellini
@ 2019-10-17 17:05 ` Rich Persaud
2019-10-17 17:30 ` Lars Kurth
0 siblings, 1 reply; 23+ messages in thread
From: Rich Persaud @ 2019-10-17 17:05 UTC (permalink / raw)
To: Stefano Stabellini
Cc: Artem Mygaiev, Lars Kurth, Lars Kurth, Andrew Cooper, Committers,
xen-devel
On Oct 17, 2019, at 12:55, Stefano Stabellini <sstabellini@kernel.org> wrote:
>
> On Thu, 17 Oct 2019, Rich Persaud wrote:
>>> On Oct 17, 2019, at 12:32, Stefano Stabellini <sstabellini@kernel.org> wrote:
>>>
>>> On Thu, 17 Oct 2019, Lars Kurth wrote:
>>>> On 16/10/2019, 17:35, "Rich Persaud" <persaur@gmail.com> wrote:
>>>>
>>>>>> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@gmail.com> 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
(b) moving text bidirectionally between source code (BSD) and documentation (any license)
(c) moving text bidirectionally between source code (BSD) and documentation (CC0)
Rich
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-17 17:05 ` Rich Persaud
@ 2019-10-17 17:30 ` Lars Kurth
2019-10-21 12:54 ` Artem Mygaiev
0 siblings, 1 reply; 23+ messages in thread
From: Lars Kurth @ 2019-10-17 17:30 UTC (permalink / raw)
To: Rich Persaud, Stefano Stabellini
Cc: Lars Kurth, Artem Mygaiev, Committers, xen-devel, Andrew Cooper
On 17/10/2019, 18:05, "Rich Persaud" <persaur@gmail.com> wrote:
On Oct 17, 2019, at 12:55, Stefano Stabellini <sstabellini@kernel.org> wrote:
>
> On Thu, 17 Oct 2019, Rich Persaud wrote:
>>> On Oct 17, 2019, at 12:32, Stefano Stabellini <sstabellini@kernel.org> wrote:
>>>
>>> On Thu, 17 Oct 2019, Lars Kurth wrote:
>>>> On 16/10/2019, 17:35, "Rich Persaud" <persaur@gmail.com> wrote:
>>>>
>>>>>> On Oct 15, 2019, at 08:27, Lars Kurth <lars.kurth.xen@gmail.com> 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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-17 17:30 ` Lars Kurth
@ 2019-10-21 12:54 ` Artem Mygaiev
2019-11-07 19:26 ` Lars Kurth
0 siblings, 1 reply; 23+ messages in thread
From: Artem Mygaiev @ 2019-10-21 12:54 UTC (permalink / raw)
To: sstabellini, persaur, lars.kurth
Cc: lars.kurth.xen, Andrew.Cooper3, committers, xen-devel
Hi Lars
On Thu, 2019-10-17 at 17:30 +0000, Lars Kurth wrote:
>
> On 17/10/2019, 18:05, "Rich Persaud" <
> persaur@gmail.com
> > wrote:
>
> On Oct 17, 2019, at 12:55, Stefano Stabellini <
> sstabellini@kernel.org
> > wrote:
> >
> > On Thu, 17 Oct 2019, Rich Persaud wrote:
> >>> On Oct 17, 2019, at 12:32, Stefano Stabellini <
> sstabellini@kernel.org
> > wrote:
> >>>
> >>> On Thu, 17 Oct 2019, Lars Kurth wrote:
> >>>> On 16/10/2019, 17:35, "Rich Persaud" <
> persaur@gmail.com
> > wrote:
> >>>>
> >>>>>> On Oct 15, 2019, at 08:27, Lars Kurth <
> lars.kurth.xen@gmail.com
> > 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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-10-21 12:54 ` Artem Mygaiev
@ 2019-11-07 19:26 ` Lars Kurth
2019-11-08 18:55 ` Stefano Stabellini
0 siblings, 1 reply; 23+ messages in thread
From: Lars Kurth @ 2019-11-07 19:26 UTC (permalink / raw)
To: Artem Mygaiev, sstabellini, persaur
Cc: lars.kurth.xen, Andrew Cooper, committers, xen-devel
Hi all,
I have received informal advice
On 21/10/2019, 06:54, "Artem Mygaiev" <Artem_Mygaiev@epam.com> wrote:
> 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
There is no LEGAL issue with using a source code license for documentation
Typically, community issues arise when the license is has a patent clause
which would act as a possible barrier to contributing to the docs (which should be low)
> (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
Fundamentally, you can’t move copyrightable content from any CC-BY-4/CC0 to BSD and vice versa without going through the process of changing a license
On the community call we discussed Andy's sphinx-docs. Andy made a strong case to keep the docset as CC-BY-4
It rests on the assumption that user docs will always be different from what's in code and thus there is no need to move anything which is copyrightable between code and the docs
Should that turn out to be wrong, there is still always the possibility of a mixed CC-BY-4 / BSD-2-Clause docset in future
So we are not painting ourselves into a corner
Regarding safety related docs, we discussed
* CC-BY-4 => this is likely to be problematic as many docs are coupled closely with source
* Dual CC-BY-4 / BSD-2-Clause licensing does not solve this problem
* BSD-2-Clause docs would enable docs that
Thus, the most sensible approach for safety related docs would be to use a BSD-2-Clause license uniformly in that case
Regards
Lars
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure
2019-11-07 19:26 ` Lars Kurth
@ 2019-11-08 18:55 ` Stefano Stabellini
0 siblings, 0 replies; 23+ messages in thread
From: Stefano Stabellini @ 2019-11-08 18:55 UTC (permalink / raw)
To: Lars Kurth
Cc: Artem Mygaiev, sstabellini, lars.kurth.xen, Andrew Cooper,
persaur, committers, xen-devel
[-- Attachment #1: Type: text/plain, Size: 2652 bytes --]
On Thu, 7 Nov 2019, Lars Kurth wrote:
> Hi all,
>
> I have received informal advice
>
> On 21/10/2019, 06:54, "Artem Mygaiev" <Artem_Mygaiev@epam.com> wrote:
>
> > 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
>
> There is no LEGAL issue with using a source code license for documentation
> Typically, community issues arise when the license is has a patent clause
> which would act as a possible barrier to contributing to the docs (which should be low)
>
> > (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
>
> Fundamentally, you can’t move copyrightable content from any CC-BY-4/CC0 to BSD and vice versa without going through the process of changing a license
>
> On the community call we discussed Andy's sphinx-docs. Andy made a strong case to keep the docset as CC-BY-4
> It rests on the assumption that user docs will always be different from what's in code and thus there is no need to move anything which is copyrightable between code and the docs
> Should that turn out to be wrong, there is still always the possibility of a mixed CC-BY-4 / BSD-2-Clause docset in future
> So we are not painting ourselves into a corner
>
> Regarding safety related docs, we discussed
> * CC-BY-4 => this is likely to be problematic as many docs are coupled closely with source
> * Dual CC-BY-4 / BSD-2-Clause licensing does not solve this problem
> * BSD-2-Clause docs would enable docs that
>
> Thus, the most sensible approach for safety related docs would be to use a BSD-2-Clause license uniformly in that case
I agree with you.
But at that point for simplicity, wouldn't it be better to use BSD-2 for
all docs?
It is difficult to be able to distinguish between "normal docs" and
"safety docs" in all cases. For instance, a description of the Xen
command line options would be required for safety, but might already
exist as docs under CC-BY-4.
What's the advantage with having some docs CC-BY-4, when we need to have
some other docs BSD-2?
(As you know, I don't care about the specific license, I am only trying
to make our life easier.)
[-- Attachment #2: Type: text/plain, Size: 157 bytes --]
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 23+ messages in thread