Re: 'Editorial' label and errata

Thanks for providing this information Ivan. I appreciate the correction on the incorrect information I gave. Now that I understand how the labels are being used I don't see it as a deal breaker if we must use multiple labels to keep in line with other WGs. We already have some duplications occurring in that document due to me misusing the labels at the beginning and including Errata labels on PRs, so I took some time today to make sure the labels were correct and left comments on closed PRs to state why I was leaving or removing labels. You can look at the errata file here to see that everything has been updated properly [1].

However, something funny just occurred here. The errata document is now not including anything for me on my end, but from the looks of it my IP has now been rate limited by github at the following URLs[2][3]. These are in the process_issues function of the errata.js script [4]. I've confirmed that this is local to my IP so it should be working for anyone who doesn't refresh the page to much and hit Github's unauthenticated rate limit.

[1]: https://w3c.github.io/vc-data-model/errata.html#section_1
[2]: https://api.github.com/repos/${dataset.githubrepo}/issues?state=all&labels=Errata
[3]: https://github.com/${dataset.githubrepo}/issues?q=label%3AErrata
[4]: https://w3c.github.io/display_errata/assets/errata.js

________________________________
From: Ivan Herman <ivan@w3.org>
Sent: Friday, November 19, 2021 5:27 AM
To: Manu Sporny <msporny@digitalbazaar.com>
Cc: W3C VC Working Group <public-vc-wg@w3.org>
Subject: Re: 'Editorial' label and errata

EXTERNAL EMAIL: This email originated outside of our organisation. Do not click links or open attachments unless you recognise the sender and know the content is safe.



On 18 Nov 2021, at 16:39, Manu Sporny <msporny@digitalbazaar.com<mailto:msporny@digitalbazaar.com>> wrote:

On 11/18/21 10:11 AM, Ivan Herman wrote:
In other words what this means is that if an issue is marked Editorial but
is /not/ an erratum, then the issue will not appear in the errata list. Is
this what you want?

No, that's not what we want. :)

The problem here is that people are getting confused about when to use the
labels and what effect they have. For example, Kyle told us to delete the
"Editorial" label yesterday because we don't use it. I then was like: "yeah,
let's delete it!" and only stopped as my hand hovered over the delete button
and was like "Hmm, something tells me that this is the wrong thing to do...
and maybe this is used for the errata thing?". So, both of the Editors
temporarily forgot about the importance of this label and were then unsure
about the combinatorial issues created as a result.

If the Editors can't keep this straight, I expect other WG members might not
be able to either.

Maybe this is an education issue

I believe it is.

and the Editors just need to remember these
rules:

* When an issue comes in, mark it with "PossibleErrata"
 and either "Editorial" or "Substantive".


If you want to have a label for "Substantive", that is fine. The errata management system does not use it, it just looks at whether it is editorial or not.

That put aside, +1.


* Classify the issue as a "v1.1 (editorial)" or "v2.0"
 issue so we know what release we intend to merge it
 into.

Right. The errata reporting (at least at this moment) is meant to work with a recommendation only and it does not look at additional labels. Ie, the Errata label should be used on (at this moment) open v1.1 issues only. Once V2.0 become a rec, then switch to those.


* After discussing with WG, replace "PossibleErrata" with
 "Errata" IF the group accepts it as an Errata.

Yes

If not,
 remove "PossibleErrata", "Editorial", and "Substantive"
 labels, but maybe not the "v1.1 (editorial)" or "v2.0"
 labels.

Yes, noting that all the errata reporting is oblivious to all issues that do not have the Errata label.


* If we close the issue, do we unmark it as "Editorial"
 or "Substantive" if it had "Errata". I'm guessing
 the answer is "no, leave it alone and just close
 the issue".

Yes.


* What happens if we use these same labels for issues?
 Should these be limited to issues, PRs, both?

Well… technically can be both. But… I believe you are trying to put too much into the errata reporting. The setup is to signal the outside world that there is a bug in the current spec, here is where you find its description, and that the WG acknowledged it is a bug. I do not think any PR that is meant to handle an official bug, starts its life directly as a PR: it is, usually, a response to a bug raised by the public in an issue. I would therefore limit the Errata label to issues.


I think we created this problem when we needed to work on three document
streams at the same time (v1.1, v1.2, and v2.0). In reality, we just ended up
deciding to publish v1.2 (renaming it to v1.1).

Possible ways forward:

1. We rename the "v1.1 (editorial)" label to "v1.1".
2. We keep the "Editorial" and "Errata" labels.
3. We get rid of the "PossibleErratum" label, I don't
  think it's useful... either something is Errata or
  it's not.

The errata reporting does not care… it is meant to suggest a process for a WG, but Errata and Editorial are the only labels that the script cares about. Note, b.t.w., that the target is really for, sort of, maintenance WG-s, and this WG has long left this state (in my books)...


The problem here, of course, is that we introduce these combinatorial rules
that everyone has to keep in their heads instead of having ONE label that we
assign to an issue... either "v<MAJOR>.<MINOR> (editorial)" or
"v<MAJOR>.<MINOR> (substantive)".

So, I think to make everything easier, we might want the errata generation
script to allow us to specify the labels that should be used when including
things in the errata file. The downside there, of course, is that every W3C WG
is going to use slightly different labels -- but maybe that's ok, because
every WG uses ReSpec in slightly different ways.

Very honestly… I am uneasy adding more to the errata management script; it has worked out over the years, and there is an "ain't broken, don't fix it" rule that I like to keep to. I would certainly not like to touch the one that is used by other WG-s out there, so any change should be on a forked version of that script.

Ivan


The goal here is to reduce everyone's cognitive burden when tracking all of
this stuff. Just some thoughts, none of this is pressing.

-- manu

--
Manu Sporny - https://www.linkedin.com/in/manusporny/
Founder/CEO - Digital Bazaar, Inc.
News: Digital Bazaar Announces New Case Studies (2021)
https://www.digitalbazaar.com/




----
Ivan Herman, W3C
Home: http://www.w3.org/People/Ivan/
mobile: +33 6 52 46 00 43
ORCID ID: https://orcid.org/0000-0003-0782-2704