how to document errata

[jlovejoy]

inspired by this PR and error :( #589
question/issue is: should we have a way to document major things like this (major as in, this scenario impacted the actual text of the license; there may be other small, minor updates we do that are not necessary to track) via a errata for releases, in release notes, ??

[jlovejoy]

(aim to discuss on call)

[wking]

On Thu, Jan 11, 2018 at 01:50:30PM -0800, Jilayne Lovejoy wrote: … via a errata for releases, in release notes, ??

I'm in favor of having a machine-readable channel. I'm not sure where we want to keep it (a separate branch here? A separate directory in master?), but having a way for folks to automatically watch for issues that impact them without having to manually read release notes would be good. An example structure would be: $ tree errata errata └── 3.0 ├── BitTorrent-1.0 │   └── extra-section-4.g └── GPL-3.0-or-later └── header-version $ head errata/3.0/*/* ==> errata/3.0/BitTorrent-1.0/extra-section-4.g <== #589 ==> errata/3.0/GPL-3.0-or-later/header-version <== #578 which would allow folks to easily find affected license-list releases and short identifiers. Details about the change and when the fix landed would be punted to the referenced issue/PR.

[wking]

Do we want to resolve this before we cut 3.1?

[bradleeedmondson]

Going to have to wait; we want to get the new licenses added and will return to this for 3.2 or later

[swinslow]

I'd lean mildly (not strongly) towards a lightweight approach here.

Something like noting errata changes in the release notes for a new release, and perhaps also in the "Notes" section of that license's entry on the license list.

With license list development occurring on GitHub, anyone is able to see the details of any (rare, but occasional) evolution of license texts, by looking directly in the license-list-XML repo. Between that and a note on the license's entry briefly describing an errata fix, I wouldn't want something heavier-weight that might slow down momentum.

[swinslow]

Now that we're regularly publishing release notes as part of each release (and aggregating them in the repo), I'd say that's perhaps the best place to document errata.

The main way I'd suggest to handle this would be to create an "errata" tag in GitHub, and if we have an issue / PR that is fixing an actual error in a previously-published license, then the PR should get tagged as "errata". If that happens, then when I'm creating the release notes at the end of the release, I'll see it when I review all the issues and PRs from that release cycle, and I can explicitly call it out in an "Errata:" section of the release notes.

I assume this would only be for actual errors in prior licenses that are being fixed, and not e.g. improvements to markup, etc.

[jlovejoy]

I like this solution, @swinslow - especially since this issue was raised before we did release notes. Luckily, we've only had a few issues like this in 12 years, so something easy and lightweight, like a tag, note in release notes, and note in Note field as needed is perfect to cover all bases.

[jlovejoy]

@swinslow - created "errata" label - I think you meant label, not tag
confirm if correct and close?!

[seabass-labrax]

Yup, sounds good to me :)

[swinslow]

Yup! "Label" is apparently what I meant in GitHub-speak :)

LGTM, I'm closing this, thanks all!