On Fri, 11 Oct 2019, Lars Kurth wrote:
> On 11/10/2019, 02:24, "Stefano Stabellini" <sstabell...@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.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
