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

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

[Lars Kurth]

Hi all,

following on from a discussion on IRC and on various other places, I think we need to try and rationalize how we handle documentation.

What we have now and what we may get in future
* http://xenbits.xen.org/docs/unstable/ (GPL-2)
* http://xenbits.xen.org/docs/sphinx-unstable-staging/ (CC-BY-4)
* Additional API documentation (with a view to enabling safety) 
* Any future documentation related to safety (requirements, designs, test cases, tracability)

Desired licenses
* There is a desire to keep http://xenbits.xen.org/docs/sphinx-unstable-staging/ CC-BY-4 only
* There is a desire to publish future documentation related to safety as CC-BY-4

Existing formats and licenses
* Hypercall ABI Documentation generated from Xen public headers
Format: kerndoc
License: typically BSD-3-Clause (documentation is generated from public headers)
* docs/designs, docs/features, docs/specs
Formats: primarily pandoc, with some files md
License: GPL-2
* docs/processs - covers internal processes
Formats: txt, with some pandoc
License: GPL-2
* docs/figs
Formats: misc
License: GPL-2
* docs/misc
Formats: txt, with some large number of pandoc, some other docs
License: GPL-2
* docs/man
Formats: pod
License: GPL-2
* Sphinx docs: docs, docs/guest-guide, docs/hypervisor-guide
Formats: rst
License: CC-BY-4

* Wiki: 
Formats: mediawiki markdown
License: CC-BY-SA-3 which has an automatic update to CC-BY-SA-4
(c) of Wiki contributions are kept by the authors

This means that the 3 most common file formats in use are
* pod
* pandoc (with some md) - these are essentially identical
* txt for legacy and old stuff
* rst

License compatibility
* GPL-2 and CC-BY-4 are compatible, but mixing means that the complete docset is GPL-2
* GPL-2 and BSD-3-Clause are compatible, but mixing means that the complete docset is GPL-2
* BSD-3-Clause and CC-BY-4 I am not 100% sure, but should not be an issue
* CC-BY-SA-4 is only one way compatible with GPLv3 (affecting content on the wiki)

The first question is whether we should convert pod to rst
* https://metacpan.org/pod/pod2rst provides a conversion tool
* man pages can be generated by rst2man
Thus, technically this should be easy and should make contributions to docs/man easier
If we do this, we should add a CONTRIBUTING file, clarifying the license in this directory

There are a set of related questions on what we would eventually merge into the sphinx
docset. I believe there is agreement that most of what is in docs today is not really
suitable, however there are a few possible exceptions
* man pages - with a variety of different contributors from different orgs. Changing license would be hard 
* API docs generated from PUBLIC headers - changing license would be impossible, but would be BSD-3-Clause
* Some wiki content (e.g. https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches and friends) 
   More than 95% of changes were from Citrix staff, so we could convert to CC-BY-4
   Most non-Citrix changes are one-line changes and could be covered by fair use
* Possibly stuff such as https://xenbits.xen.org/docs/unstable/support-matrix.html (which is currently GPL-2,
   but we could relicense to say GPL-2 and CC-BY-4 if we had to)
The implication is that the sphinx docs would not be fully CC-BY-4, but the bulk of the pages would be

* 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

Other pages in docs that may be useful for the sphinx docs should essentially be re-written, 
so we would be fine from a licensing perspective. That means that over time, we could get rid of 
pandoc and text files in docs/misc, docs/designs, docs/features, docs/specs which
have not really built a lot of traction.

Related to this is the general question, whether we would ever copy code from source to docs
and vice versa and to which degree. This is an unknown to me: I think in practice we have not seen
much or even any of this in the past.

On licensing, we should try and make the docs directory clean, e.g.
* We should set the default to CC-BY-4 (e.g. through a contributing file in docs)
* And specifically use GPL-2 for directories such as docs/misc, docs/man, ...

In any case, this seems all a little bit of a mess at the moment and I think we need to
agree on a foundation to get us to a better state. This mail is a start and intends to gather
input and will eventually lead to a more concrete proposal.

If I have missed anything, feel free to add

Best Regards
Lars



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

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

[Andrew Cooper]

On 10/10/2019 13:34, Lars Kurth wrote:
> Hi all,
>
> following on from a discussion on IRC and on various other places, I think we need to try and rationalize how we handle documentation.
>
> What we have now and what we may get in future
> * http://xenbits.xen.org/docs/unstable/ (GPL-2)
> * http://xenbits.xen.org/docs/sphinx-unstable-staging/ (CC-BY-4)
> * Additional API documentation (with a view to enabling safety) 
> * Any future documentation related to safety (requirements, designs, test cases, tracability)
>
> Desired licenses
> * There is a desire to keep http://xenbits.xen.org/docs/sphinx-unstable-staging/ CC-BY-4 only
> * There is a desire to publish future documentation related to safety as CC-BY-4

Its probably worth nothing that the
http://xenbits.xen.org/docs/sphinx-unstable-staging/ URL is only
transitional.

When Sphinx is more ready for primetime, I was thinking of using
http://xenbits.xen.org/docs/xen/, and using the Sphinx support for
multiple versions, which would end up becoming docs/xen/{4.13,...,latest}/

> Existing formats and licenses
> * Hypercall ABI Documentation generated from Xen public headers
> Format: kerndoc
> License: typically BSD-3-Clause (documentation is generated from public headers)

Its homegrown markup&perl, superimposed on what used to be doxygen in
the past.

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.

> * docs/designs, docs/features, docs/specs
> Formats: primarily pandoc, with some files md
> License: GPL-2
> * docs/processs - covers internal processes
> Formats: txt, with some pandoc
> License: GPL-2
> * docs/figs
> Formats: misc
> License: GPL-2
> * docs/misc
> Formats: txt, with some large number of pandoc, some other docs
> License: GPL-2
> * docs/man
> Formats: pod
> License: GPL-2
> * Sphinx docs: docs, docs/guest-guide, docs/hypervisor-guide
> Formats: rst
> License: CC-BY-4

This is the intention, but hasn't taken effect while my series is still
pending.  For now, strictly speaking it is still GPL-2.

>
> * Wiki: 
> Formats: mediawiki markdown
> License: CC-BY-SA-3 which has an automatic update to CC-BY-SA-4
> (c) of Wiki contributions are kept by the authors
>
> This means that the 3 most common file formats in use are
> * pod
> * pandoc (with some md) - these are essentially identical
> * txt for legacy and old stuff
> * rst
>
> License compatibility
> * GPL-2 and CC-BY-4 are compatible, but mixing means that the complete docset is GPL-2
> * GPL-2 and BSD-3-Clause are compatible, but mixing means that the complete docset is GPL-2
> * BSD-3-Clause and CC-BY-4 I am not 100% sure, but should not be an issue
> * CC-BY-SA-4 is only one way compatible with GPLv3 (affecting content on the wiki)
>
> The first question is whether we should convert pod to rst
> * https://metacpan.org/pod/pod2rst provides a conversion tool
> * man pages can be generated by rst2man
> Thus, technically this should be easy and should make contributions to docs/man easier
> If we do this, we should add a CONTRIBUTING file, clarifying the license in this directory

One thing I have done is put SPDX tags on every *.rst file.  What I
haven't found is a nice way to insert one into the *.drawio.svg files,
but I should probably finish off some of my experimentation TODOs.

An easy way out is to just say "look at the SPDX tag", but then we end
up with a docset which is a mess of licenses, still can't be easily
built upon.

> There are a set of related questions on what we would eventually merge into the sphinx
> docset. I believe there is agreement that most of what is in docs today is not really
> suitable, however there are a few possible exceptions
> * man pages - with a variety of different contributors from different orgs. Changing license would be hard

But certainly not impossible.

> * API docs generated from PUBLIC headers - changing license would be impossible, but would be BSD-3-Clause

The code, yes, but I'm expecting that to be orthogonal in the long run.

> * Some wiki content (e.g. https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches and friends) 
>    More than 95% of changes were from Citrix staff, so we could convert to CC-BY-4
>    Most non-Citrix changes are one-line changes and could be covered by fair use
> * Possibly stuff such as https://xenbits.xen.org/docs/unstable/support-matrix.html (which is currently GPL-2,
>    but we could relicense to say GPL-2 and CC-BY-4 if we had to)
> The implication is that the sphinx docs would not be fully CC-BY-4, but the bulk of the pages would be

Would be what?

~Andrew

>
> * 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
>
> Other pages in docs that may be useful for the sphinx docs should essentially be re-written, 
> so we would be fine from a licensing perspective. That means that over time, we could get rid of 
> pandoc and text files in docs/misc, docs/designs, docs/features, docs/specs which
> have not really built a lot of traction.
>
> Related to this is the general question, whether we would ever copy code from source to docs
> and vice versa and to which degree. This is an unknown to me: I think in practice we have not seen
> much or even any of this in the past.
>
> On licensing, we should try and make the docs directory clean, e.g.
> * We should set the default to CC-BY-4 (e.g. through a contributing file in docs)
> * And specifically use GPL-2 for directories such as docs/misc, docs/man, ...
>
> In any case, this seems all a little bit of a mess at the moment and I think we need to
> agree on a foundation to get us to a better state. This mail is a start and intends to gather
> input and will eventually lead to a more concrete proposal.
>
> If I have missed anything, feel free to add
>
> Best Regards
> Lars

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

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

[Lars Kurth]

On 10/10/2019, 18:05, "Andrew Cooper" <Andrew.Cooper3@citrix.com> wrote:

    On 10/10/2019 13:34, Lars Kurth wrote:
    > Hi all,
    >
    > following on from a discussion on IRC and on various other places, I think we need to try and rationalize how we handle documentation.
    >
    > What we have now and what we may get in future
    > * http://xenbits.xen.org/docs/unstable/ (GPL-2)
    > * http://xenbits.xen.org/docs/sphinx-unstable-staging/ (CC-BY-4)
    > * Additional API documentation (with a view to enabling safety) 
    > * Any future documentation related to safety (requirements, designs, test cases, tracability)
    >
    > Desired licenses
    > * There is a desire to keep http://xenbits.xen.org/docs/sphinx-unstable-staging/ CC-BY-4 only
    > * There is a desire to publish future documentation related to safety as CC-BY-4
    
    Its probably worth nothing that the
    http://xenbits.xen.org/docs/sphinx-unstable-staging/ URL is only
    transitional.
    
    When Sphinx is more ready for primetime, I was thinking of using
    http://xenbits.xen.org/docs/xen/, and using the Sphinx support for
    multiple versions, which would end up becoming docs/xen/{4.13,...,latest}/
    
    > Existing formats and licenses
    > * Hypercall ABI Documentation generated from Xen public headers
    > Format: kerndoc
    > License: typically BSD-3-Clause (documentation is generated from public headers)
    
    Its homegrown markup&perl, superimposed on what used to be doxygen in
    the past.

Oh, I forgot
    
    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.
    
    > * docs/designs, docs/features, docs/specs
    > Formats: primarily pandoc, with some files md
    > License: GPL-2
    > * docs/processs - covers internal processes
    > Formats: txt, with some pandoc
    > License: GPL-2
    > * docs/figs
    > Formats: misc
    > License: GPL-2
    > * docs/misc
    > Formats: txt, with some large number of pandoc, some other docs
    > License: GPL-2
    > * docs/man
    > Formats: pod
    > License: GPL-2
    > * Sphinx docs: docs, docs/guest-guide, docs/hypervisor-guide
    > Formats: rst
    > License: CC-BY-4
    
    This is the intention, but hasn't taken effect while my series is still
    pending.  For now, strictly speaking it is still GPL-2.

I was basing this on the assumption the series will go in
    
    > * Wiki: 
    > Formats: mediawiki markdown
    > License: CC-BY-SA-3 which has an automatic update to CC-BY-SA-4
    > (c) of Wiki contributions are kept by the authors
    >
    > This means that the 3 most common file formats in use are
    > * pod
    > * pandoc (with some md) - these are essentially identical
    > * txt for legacy and old stuff
    > * rst
    >
    > License compatibility
    > * GPL-2 and CC-BY-4 are compatible, but mixing means that the complete docset is GPL-2
    > * GPL-2 and BSD-3-Clause are compatible, but mixing means that the complete docset is GPL-2
    > * BSD-3-Clause and CC-BY-4 I am not 100% sure, but should not be an issue
    > * CC-BY-SA-4 is only one way compatible with GPLv3 (affecting content on the wiki)
    >
    > The first question is whether we should convert pod to rst
    > * https://metacpan.org/pod/pod2rst provides a conversion tool
    > * man pages can be generated by rst2man
    > Thus, technically this should be easy and should make contributions to docs/man easier
    > If we do this, we should add a CONTRIBUTING file, clarifying the license in this directory
    
    One thing I have done is put SPDX tags on every *.rst file.  What I
    haven't found is a nice way to insert one into the *.drawio.svg files,
    but I should probably finish off some of my experimentation TODOs.
    
    An easy way out is to just say "look at the SPDX tag", but then we end
    up with a docset which is a mess of licenses, still can't be easily
    built upon.

I think a per-directory approach is generally better + use SPDX tags
where it can easily be added.
And it's easy enough to do
    
    > There are a set of related questions on what we would eventually merge into the sphinx
    > docset. I believe there is agreement that most of what is in docs today is not really
    > suitable, however there are a few possible exceptions
    > * man pages - with a variety of different contributors from different orgs. Changing license would be hard
    
    But certainly not impossible.

Agreed
    
    > * API docs generated from PUBLIC headers - changing license would be impossible, but would be BSD-3-Clause
    
    The code, yes, but I'm expecting that to be orthogonal in the long run.
    
    > * Some wiki content (e.g. https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches and friends) 
    >    More than 95% of changes were from Citrix staff, so we could convert to CC-BY-4
    >    Most non-Citrix changes are one-line changes and could be covered by fair use
    > * Possibly stuff such as https://xenbits.xen.org/docs/unstable/support-matrix.html (which is currently GPL-2,
    >    but we could relicense to say GPL-2 and CC-BY-4 if we had to)
    > The implication is that the sphinx docs would not be fully CC-BY-4, but the bulk of the pages would be
    
    Would be what?
    
CC-BY-4

Lars


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

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

[Stefano Stabellini]

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.

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

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.


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

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

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

[Jan Beulich]

On 10.10.2019 20:30, Lars Kurth wrote:
> On 10/10/2019, 18:05, "Andrew Cooper" <Andrew.Cooper3@citrix.com> wrote:
>     On 10/10/2019 13:34, Lars Kurth wrote:
>     > Existing formats and licenses
>     > * Hypercall ABI Documentation generated from Xen public headers
>     > Format: kerndoc
>     > License: typically BSD-3-Clause (documentation is generated from public headers)
>     
>     Its homegrown markup&perl, superimposed on what used to be doxygen in
>     the past.
> 
> Oh, I forgot
>     
>     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.

Well, for migration v2 having the spec in a text file seems sensible
to me. For the public ABI, however, I think it's more helpful to have
the doc next to the actual definitions. Considering the possible use
of languages other than C I can certainly see why separating both
would be even more clean, but I think here we want to weigh practical
purposes against cleanliness.

Jan

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

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

[Artem Mygaiev]

Hi Lars

On Thu, 2019-10-10 at 12:34 +0000, Lars Kurth wrote:
> * Possibly stuff such as 
> https://urldefense.com/v3/__https://xenbits.xen.org/docs/unstable/support-matrix.html__;!K6dmGCEab4ueJg!lwAwYJi7cUkbX7CUXnOD9i7laj_9xcyafF714u6PO04tu0CYUKDHWBHAy2XD0mvEiA$
>   (which is currently GPL-2,
>    but we could relicense to say GPL-2 and CC-BY-4 if we had to)
> The implication is that the sphinx docs would not be fully CC-BY-4,
> but the bulk of the pages would be
> 
> * 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
> 

Yes, I think we will have to use some API docs in safety related
documentation. But I do not see any issue with that because using
"description" part of headers in documentation can be treated as "fair
use" and thus will not create a license conflict as confirmed in 
https://www.gnu.org/licenses/gpl-faq.en.html#SourceCodeInDocumentation

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

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

[Lars Kurth]

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.

@Andy: as you have maybe a stronger view on this, it would be good
to get your view

Best Regards
Lars
 




    

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

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

[Lars Kurth]

On 11/10/2019, 09:32, "Jan Beulich" <jbeulich@suse.com> wrote:

    On 10.10.2019 20:30, Lars Kurth wrote:
    > On 10/10/2019, 18:05, "Andrew Cooper" <Andrew.Cooper3@citrix.com> wrote:
    >     On 10/10/2019 13:34, Lars Kurth wrote:
    >     > Existing formats and licenses
    >     > * Hypercall ABI Documentation generated from Xen public headers
    >     > Format: kerndoc
    >     > License: typically BSD-3-Clause (documentation is generated from public headers)
    >     
    >     Its homegrown markup&perl, superimposed on what used to be doxygen in
    >     the past.
    > 
    > Oh, I forgot
    >     
    >     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.
    
    Well, for migration v2 having the spec in a text file seems sensible
    to me. For the public ABI, however, I think it's more helpful to have
    the doc next to the actual definitions. Considering the possible use
    of languages other than C I can certainly see why separating both
    would be even more clean, but I think here we want to weigh practical
    purposes against cleanliness.

I think that is an area where we need to build some consensus. The problem
falls under what is considered "traceability" in safety speak: in other words, 
for the ABI documentation use-case it must be easy to be able to
keep documentation and code in sync. And ideally, we would be able to
check this automatically somehow, or have a bot provide hints such as 
"You changed XYZ and should have a look and check whether ABC needs
changing also".

I have thought about the problem of "traceability" for some time, which
goes far beyond what we need for this use-case. Typical things that need
to be maintained for a "traceable (safety) documentation set" are

## Keeping key docs and code in sync 
The use-cases here are things such as
- keep man pages and xl sources in sync
- keep ABI docs and headers in sync
- keep documents such as the migration b2 spec in sync with
  actual source
 
This is a problem we already have today and where we do this often
fairly poorly manually (as can be seen on how out-of-date
man pages often are)

Possible solutions for this are
- store docs alongside headers (maybe using the same base
file name) => that would work for ABI docs

- have some tagging or meta-information scheme which links
specific source files to docs files => that would work for most
other docs (albeit not always perfectly - e.g. when functionality
is spread over many files and just portions of them)

For example: tools/xl/xl_cmdtable.c  
is linked to files in docs/man/xl*

This means creating a bot/tool which warns that when you change
foo.c to also look at foo.rst and/or ../../docs/.../bar.rst should be
relatively straightforward. It would require some initial effort
to create initial mappings, but these would never really change,
unless we refactor code significantly.
     
## Keeping dependent documents (or portions of documents) in sync
This is something we have not really faced, because we do not
have a lot of docs.  

In a large documentation set having the right chapter/tree
structure enables this. In waterfall software engineering
models, where you start off with high-level documents/
requirements/specs/etc. documents which become
increasingly detailed this is done through a chapter/tree
structure, with the capability to make separate documents
(or sections thereof) on other documents (or sections
thereof). When you change something, a tool such as DOORS 
forces you review and sign off child documents.

This is conceptually similar to what we would need for
"linking" sources to docs as outlined above, only that
the "linking" is between docs. It would also be easy enough
to check and highlight, what else may have to be looked at.  

## Proving that your tests verify design claims and that *all claims* are tested
This is typically the hardest problem to solve. It requires
for test cases (be it a document or actual code) to
link to claims (in a design, architecture, spec, ...)
and to prove that all of them are tested.

If there is linkage capability, then it is straightforward
to verify automatically that all your branches have
test-case leaves in your documentation tree. But at least
in a safety context you would also have to augment this
with code coverage information. 

But for the purpose of this discussion, this use-case
does not add any extra linkage capability other than
being able to tell whether a piece of doc/code
is a test case.

## In summary
I feel that having some basic linkage mechanism    
between key documents and key documents of
code is generally valuable for the community as a
whole, if we can tie to some checking into it.

For rst docs we already have linkage via the
".. toctree::" directives, which may be entirely
sufficient. But we don't have linkage from source
to docs. 

Building some checking around this should not
be too hard, in particular in light of the CIv2
checking we agreed (but is somewhat stalled).

Enabling the same checks to be run locally (before)
sending a patch, should also not be too hard.

I am just raising ideas at this stage. Any opinions
are highly welcome.

Regards
Lars 



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

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

[Stefano Stabellini]

[-- Attachment #1: Type: text/plain, Size: 6446 bytes --]

On Fri, 11 Oct 2019, Lars Kurth wrote:
> On 11/10/2019, 09:32, "Jan Beulich" <jbeulich@suse.com> wrote:
> 
>     On 10.10.2019 20:30, Lars Kurth wrote:
>     > On 10/10/2019, 18:05, "Andrew Cooper" <Andrew.Cooper3@citrix.com> wrote:
>     >     On 10/10/2019 13:34, Lars Kurth wrote:
>     >     > Existing formats and licenses
>     >     > * Hypercall ABI Documentation generated from Xen public headers
>     >     > Format: kerndoc
>     >     > License: typically BSD-3-Clause (documentation is generated from public headers)
>     >     
>     >     Its homegrown markup&perl, superimposed on what used to be doxygen in
>     >     the past.
>     > 
>     > Oh, I forgot
>     >     
>     >     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.
>     
>     Well, for migration v2 having the spec in a text file seems sensible
>     to me. For the public ABI, however, I think it's more helpful to have
>     the doc next to the actual definitions. Considering the possible use
>     of languages other than C I can certainly see why separating both
>     would be even more clean, but I think here we want to weigh practical
>     purposes against cleanliness.
> 
> I think that is an area where we need to build some consensus. The problem
> falls under what is considered "traceability" in safety speak: in other words, 
> for the ABI documentation use-case it must be easy to be able to
> keep documentation and code in sync. And ideally, we would be able to
> check this automatically somehow, or have a bot provide hints such as 
> "You changed XYZ and should have a look and check whether ABC needs
> changing also".
> 
> I have thought about the problem of "traceability" for some time, which
> goes far beyond what we need for this use-case. Typical things that need
> to be maintained for a "traceable (safety) documentation set" are
> 
> ## Keeping key docs and code in sync 
> The use-cases here are things such as
> - keep man pages and xl sources in sync
> - keep ABI docs and headers in sync
> - keep documents such as the migration b2 spec in sync with
>   actual source
>  
> This is a problem we already have today and where we do this often
> fairly poorly manually (as can be seen on how out-of-date
> man pages often are)
> 
> Possible solutions for this are
> - store docs alongside headers (maybe using the same base
> file name) => that would work for ABI docs
> 
> - have some tagging or meta-information scheme which links
> specific source files to docs files => that would work for most
> other docs (albeit not always perfectly - e.g. when functionality
> is spread over many files and just portions of them)
> 
> For example: tools/xl/xl_cmdtable.c  
> is linked to files in docs/man/xl*
> 
> This means creating a bot/tool which warns that when you change
> foo.c to also look at foo.rst and/or ../../docs/.../bar.rst should be
> relatively straightforward. It would require some initial effort
> to create initial mappings, but these would never really change,
> unless we refactor code significantly.
>      
> ## Keeping dependent documents (or portions of documents) in sync
> This is something we have not really faced, because we do not
> have a lot of docs.  
> 
> In a large documentation set having the right chapter/tree
> structure enables this. In waterfall software engineering
> models, where you start off with high-level documents/
> requirements/specs/etc. documents which become
> increasingly detailed this is done through a chapter/tree
> structure, with the capability to make separate documents
> (or sections thereof) on other documents (or sections
> thereof). When you change something, a tool such as DOORS 
> forces you review and sign off child documents.
> 
> This is conceptually similar to what we would need for
> "linking" sources to docs as outlined above, only that
> the "linking" is between docs. It would also be easy enough
> to check and highlight, what else may have to be looked at.  
> 
> ## Proving that your tests verify design claims and that *all claims* are tested
> This is typically the hardest problem to solve. It requires
> for test cases (be it a document or actual code) to
> link to claims (in a design, architecture, spec, ...)
> and to prove that all of them are tested.
> 
> If there is linkage capability, then it is straightforward
> to verify automatically that all your branches have
> test-case leaves in your documentation tree. But at least
> in a safety context you would also have to augment this
> with code coverage information. 
> 
> But for the purpose of this discussion, this use-case
> does not add any extra linkage capability other than
> being able to tell whether a piece of doc/code
> is a test case.
> 
> ## In summary
> I feel that having some basic linkage mechanism    
> between key documents and key documents of
> code is generally valuable for the community as a
> whole, if we can tie to some checking into it.
> 
> For rst docs we already have linkage via the
> ".. toctree::" directives, which may be entirely
> sufficient. But we don't have linkage from source
> to docs. 
> 
> Building some checking around this should not
> be too hard, in particular in light of the CIv2
> checking we agreed (but is somewhat stalled).
> 
> Enabling the same checks to be run locally (before)
> sending a patch, should also not be too hard.
> 
> I am just raising ideas at this stage. Any opinions
> are highly welcome.

As long as the linking between code and docs is done with a simple
unobtrusive tag, I think it is a good idea. Once we have a proper
checkpatch script in the tree, we could imagine adding a check to
it to see whether any docs need updating.

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

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

[Stefano Stabellini]

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

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

[P S]

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

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

[Rich Persaud]

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

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

[Lars Kurth]

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

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

[Rich Persaud]

> 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

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

[Lars Kurth]

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

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

[Stefano Stabellini]

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

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

[Rich Persaud]

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

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

[Stefano Stabellini]

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

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

[Rich Persaud]

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

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

[Lars Kurth]

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

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

[Artem Mygaiev]

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

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

[Lars Kurth]

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

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

[Stefano Stabellini]

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