[Development] Documenting 3rd party license code (with SPDX?)

[Kai Koehne]

tl;dr: Does anyone have experience with SPDX?

Qt modules contain quite some 3rd party code under various (permissible) licenses. We've been listening these in the
documentation, but this is certainly improvable - while the list is (hopefully) comprehensive, it gives users little help in where the 
3rd party code is actually used (library, plugin, platform), what to do to avoid it (configure arguments?), how to acknowledge 
distribution requirements ...

The list is also managed centrally in qtdoc.git, which requires a lot of effort to keep up to date with the other modules. 
My first step to improve the situation is therefore to move the documentation to where the code is actually located. 
At the same time I think it's a good idea not to just write .qdoc, but use a more specific format that then can be processed.

What I'd like to suggest eventually is that
- every code in our git modules where we don't have the relicensing rights for needs to be under a '3rdparty' folder
- every folder needs a structured document that describes things like the license(s), copyright, where the code originated ...

And that we then automatically process the documents to generate the documentation.

Anyhow, first we have to settle on a file format. So far I have had a look at two file formats:

* README.Chromium *

Chromium mandates that every folder under 3rdparty needs a semi-structured file called 'README.chromium':

https://src.chromium.org/viewvc/chrome/trunk/src/third_party/README.chromium.template

There's then a python tool that takes some of the information, and generates the credits information page (chrome://credits)

The file format is pretty light-weight and informal, but this has its drawbacks: Namely that the tool doesn't really validate much, and there 
seems to be some ongoing confusion on what exactly the individual fields should contain. Take e.g. URL: This is rendered in Chrome as 
a link to the 'Homepage' of the project, but a lot of documents actually link to individual downloads there. It's also focused on
credits page, so it would need to be extended ...

* SPDX *

SPDX (Software Package Data Exchange) "is a standard format for communicating the components, licenses and copyrights associated 
with a software package." The probably most popular thing they have is a list of standard names for different licenses

https://spdx.org/licenses/

But there's also an elaborate standard how to document 'software packages'. The documents can apparently both be written in Excel,
RDF (XML), and Key/Value formats, there are (Java) tools to convert them, and there's a lot of tooling around it. But honestly speaking I've 
troubles wrapping my mind around the standard. It seems quite heavy, and I'm lost how exactly to apply it to our situation. But I do see 
that, if a lot of customers/upstream distributions would like to use SPDX files too, using it directly in Qt might be beneficial.


So, does anyone had exposure to SPDX already, and maybe have an idea how it could be used for our 3rdparty directories in Qt?
Personally I'm leaning towards defining our own customized JSON format that uses the best things from SPDX (standardized license id's)
and README.Chromium. But I'd be glad to discuss with people interested in the topic :)

Thanks for reading

Kai

-- 
Kai Köhne, Senior Manager R&D | The Qt Company

The Qt Company GmbH, Rudower Chaussee 13, D-12489 Berlin
Geschäftsführer: Mika Pälsi, Juha Varelius, Mika Harjuaho. Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB 144331 B