[Development] Rules for Third-Party components in Qt 5.8 onwards
Kai.Koehne at qt.io
Tue Dec 13 17:20:35 CET 2016
(I'll try to answer some comments made in the gerrit review here. IMO gerrit
works great for editorial stuff, but not for more substantial things).
> [Tobias Hunger]
> I would make the homepage mandatory in the attribution file. That information is critical IMHO when you want to find out more about that piece of code.
If there's a homepage, by all means, specify the "Homepage" property. I didn't make it mandatory though because we have code where there's just no legitimate upstream homepage, most often because Qt itself is the 'upstream'. Putting "www.qt.io" here would be possible, but also confusing ;) That's e.g. the case for some of the text codes, like http://doc-snapshots.qt.io/qt5-5.8/qtcore-attribution-qtsciicodec.html.
> I would also suggest to add something about giving the exact revision of the code (full download link, repo where the code came from and exact version specification in that repo) in the commit message when initially > importing the code or when updating it. For my taste it is currently too hard to find out which exact versions of stuff we use.
It is very important to track the upstream version used, so that we can easily see when something is outdated and track custom changes done before it's imported.
You should not only put that in the commit message though. In qt_attribution.json file you should set a 'Version' field that you should set to the official property. This could also be e.g. an SHA if there's no marked upstream version. In addition, you should set the 'DownloadLocation' field that should link to the upstream package / installer / ...
When creating the initial qt_attribution.json files, I was adding this information when it was obvious, but I didn't do much due diligence. I'd appreciate it if contributors/maintainers would complete the information wherever possible.
> [Robin Burchell on Copyright field being mandatory]
> Having the license for instance as mandatory seems quite reasonable, but I'm less certain about this. Keeping it maintained could be quite a burden, and for complex software I can imagine it ending up quite long. Does > it have significant value? What's the purpose of it?
> For example, I looked at another project I've been a significant part of, started around 2002, with a fairly constant stream of random contributors. There are 135 unique "Copyright" lines throughout the source,
> although a number of these are duplicated authors with different year information. The most frequently repeated lines are repeated >100 times.
I'm a bit unsure about the extra 'Copyright' field myself, especially if it duplicates the Copyright in the license file (like it is for the BSD licenses). I added it because it's sometimes requested by customers, and is also part of e.g. the SPDX and debian/copyright specifications [1,2].
In general, the copyright field shows the user a) when the copyright protection might run out and b) whom to contact in case one has questions. Also, even if not strictly required by some licenses, it is also acknowledging the original authors. So, I do think it adds value, also to the documentation.
In practical terms, often bigger projects tend to have generic acknowledgements like
Copyright XXXX the <project name> authors
Copyright XXXX the <main author> and contributors
If that is done upstream, it obviously is the right thing to keep it like that in the qt_attribution.json file, too. I can try to find out whether it's also ok to consolidate on our own.
So, in summary, I'd keep the field mandatory, potentially consolidating it to one name. If the Copyright is also part of the License text itself (like for the typical BSD license), I've duplicated the lines in the past.
If we decide to keep it this way, I can try to clarify it in the QUIP.
More information about the Development