Repository labels need to be defined

[andorsk]

Right now we don't have labels to maintain the repository. Editors need to agree on a set of labels to prioritize issues for resolution and then apply those tags to existing and new issues.

This issue is specifically scoped for determining the labels themselves. A new issue shall be generated for resolving old issues.

Here's some proposals that have been made:

• Proposed Close: When an issue has been flagged for review by the community, with the intent to close the issue, given no objections. Once tagged, a TATF member MUST object within 5 calendar days to reopen discussion of the issue. If there is no objection within 5 calendar days, the proposed resolution will be applied to the spec by one of the Editors and the issue will be closed with no further discussion.

This intent of this tag is to help "queue" issues that need review.

As creator of the issue, I'd also like to propose that these definitions need to be available somewhere. Possibly in the CONTRIBUTING.md or GOVERNANCE.md file, for future accessibility later.

[andorsk]

I'd like to propose here that rather than starting from scratch, we use existing repositories as guidelines of how to construct the labels:

Here's one that might be worth reviewing: https://github.com/OpenMined/PySyft/issues

[andorsk]

This has the labels in JSON: https://api.github.com/repos/OpenMined/PySyft/labels

[sankarshanmukhopadhyay]

I'd like to propose here that rather than starting from scratch, we use existing repositories as guidelines of how to construct the labels:

Here's one that might be worth reviewing: https://github.com/OpenMined/PySyft/issues

Since this repository is set up primarily for text-based content (and not code) my suggestion would be to start with a small set such as

• FutureRelease (for topics which would be in a 1.x or 2.x version/branch of the document)
• Discussion (for topics which are not yet ready to be presented as well formed idea)
• NewTopic (for any new topic which is being introduced)
• Correction (any corrections or fixes in the existing text in current branch)

I made the above list after pondering a bit about what gets discussed at the meetings and reading through the minutes.

[andorsk]

@sankarshanmukhopadhyay This is good but I'd like to propose we have a few more on top of this. Understood your concern about tagging getting numerous, but I also think some extra information would provide some value to contributors.

My suggestion here is we need some prioritization along with the above. Ultimately there will be N tickets and we need to provide a subset for the meeting. So my first suggestion is maintaining a priority list of Low Medium High, along with @talltree's proposal for Proposed Close. The advantage here is it would help the TF address the right issues in the right order.

Additional tags I think would be helpful:

• help wanted tag <- in case nobody has time.
• good first issue <- for newcomers.
• some version tag <- related to the version on the specs. This one maybe waits until a future round.

[andorsk]

re: discussions, we could open up the Discussions feature on Github if that makes sense, to allow for discussions that aren't yet ready for issues.

[talltree]

re: discussions, we could open up the Discussions feature on Github if that makes sense, to allow for discussions that aren't yet ready for issues.

@andorsk, I haven't used GitHub Discussions but I've heard good things about it. This might be especially helpful during the public review period. I will put this on the agenda for tomorrow's TATF meetings.

For folks new to GitHub Discussions, this guide is a really good introduction.

[talltree]

Having spent two years as an editor of the W3C Decentralized Identifiers (DIDs) 1.0 spec — and working with some of the most experienced spec editors I know — here is the list of general tags we used to organize and manage our GitHub issues list (Note: I'm leaving out DID-spec-specific tags and adapting a few of the tag names):

• priority-1
• priority-2
• priority-3
• defer-to-V2
• editorial
• substantial
• needs-special-group
• needs-proposal
• needs-PR
• PR-exists
• last-call-to-close

Commentary:

• The priority labels are obvious — just 3 levels to help us concentrate on the highest priority issues.
• The defer label are for when we make a decision that an issue can be deferred, either to the community review period, the public review period, or V2.
• editorial and substantial just help us understand the nature of issue and whose attention is needed.
• The needs tags clarify the next step needed to resolve the issue:
  • a special subgroup to discuss it and come up with a proposal
  • a proposal
  • a PR to be written based on an existing proposal which has rough consensus
• PR-exists says the issue is remains open pending closure on the PR
• last-call-to-close is applied when consensus has been reached on closure and triggers the 5 day waiting period before automatic closure

[andorsk]

Yea... @talltree this looks like a solid list. Maybe w/ @sankarshanmukhopadhyay correction tag as well. Seems like for this repo, correction would be kinda like bug in software development terms.

I don't mind setting this up, if that's the tags we want, as well as putting something on the repoCONTRIBUTING.md file for the review/tagging process.

[talltree]

@andorsk +1 to adding the correction label as well.

I've put this on the agenda for the TATF calls tomorrow to see if members have any further input, but once we've done that, it would be fantastic if you want to set these up. Note that I've adding comments to a handful of issues tonight to suggest what the proposed labels from this list would be so we can test this with the TF tomorrow.

[andorsk]

Awesome. Will do. @wenjing or @talltree I'll need the ability to create labels on the repo. As of now, that is not possible for my credentials.

Let's bundle this access issue a bigger access/repo management issue. I.e deciding who can do what, and enabling them so they can help.

[andorsk]

Reference documentation by @talltree https://wiki.trustoverip.org/display/HOME/GitHub+Issues+Management+Process. Labels added there as well.

[andorsk]

Add needs editor review. Action item: Fill out a table with details about the labels.

[a-fox]

Regarding labels, they should serve at least three purposes: 1) They should be obvious for new people, making it easier for anybody to jump into the issues. 2) They should be aligned with what type of issues are raised during the work (no label-waste) 3) They should make issue handling more efficient by helping to provide meta-information for sorting, easy scanning, categorising, etc.

I like a lot the example @andorsk shared, especially the way they categorize the labels. It helps tremendously on readibility and usability.

With these in mind, I would propose the following changes to the labels @talltree listed:

• Categorize with: Priority, Type, State. An issue should be able to be tagged with only one label per category.
• Make priority labels more obvious and readable by using words High-Medium-Low, e.g. "Priority: 1 - High"
• instead of ‘defer-to-v2’, I would just use milestones to track versions. This has subsequent help for release process later. Also, we can use a state for this as well (e.g. State: Deferred)
• Define content-defining labels more clearly, e.g. "Type: Editorial", "Type: Content", "Type: Admin" ('substantial' is not evident for non-native speakers. I thought initially it meant that this is a label for a big issue) – I would argue that defining more detailed content-definitions (like diagram, correction, new section) may become fast counter-productive. i may be wrong, but I would rather wait for the need to be formed first. It's also easy to add standard non-categorized labels to support that.
• I think rest are state-labels which denote the process step, e.g. "State: Group discussion needed". As this is the largest label-category, it could also be used without the 'State' -prefix.

So the list would read:

• Priority: 1 - High
• Priority: 2 - Medium
• Priority: 3 - Low
• Type: Editorial
• Type: Content
• Type: Admin
• State: Needs Group discussion
• State: Needs Proposal
• State: Needs PR
• State: Needs review
• State: Deferred for later
• State: Accepted

[andorsk]

@a-fox nice proposal. I think that's a fantastic idea. Milestones would definitely work, but it does introduce another "thing" to learn which was my only concern. That being said: it eventually flows better into tracking things, so it can make sense.

On the list above, I do think @talltree's point about:

last-call-to-close probably should be there. With your updated label: State: Last Call to Close. This is to give some latency to the review process. I.e if you weren't on the meeting, you still have some time to review before it closes out.

Also Type: Correction per @sankarshanmukhopadhyay

I'll need to think a little bit more about how to put everyone's feedback together, but this is a great discussion to have and I love the community feedback on it. I think we are getting really close

The PR's in theory are trackable right on the issue as well, but again, another thing to learn. Trying to not have too much cognitive load here, but on the flip side it's pretty straight forward.

We aren't using projects yet, and I'm not sure we should...

[andorsk]

One thing I'll mention here: We can adjust the labels names after, without having to redo the actual labelling. Github doesn't use the name as an id, but it's a reference to a pointer for an id. The point is here, if something updates later on the labels, we can update it without doing a whole bunch of work after, so we aren't at a point of no return for existing labels. Creating new ones would require some work to apply though.

[talltree]

@a-fox Thanks for the in-depth analysis and recommendation. I did a little research on best practices for GitHub issue labels and found this article that advises exactly the same three categories (priority, type, status). So I took your advice and updated the Github Issues Management wiki page per your suggestions, while also including the suggestions of @andorsk and @sankarshanmukhopadhyay.

I also took the advice of the W3C editors and made all labels 100% lowercase.

The full explanation of each label is in the table on the wiki page, but for easy reference here, the revised list is:

• priority: critical
• priority: high
• priority: medium
• priority: low
• type: editorial
• type: content
• type: correction
• type: formatting
• type: figure
• status: unassigned
• status: in-progress
• status: blocked
• status: on-hold
• status: deferred
• status: abandoned
• status: PR-needed
• status: PR-in-progress
• status: PR-completed
• status: PR-accepted
• status: last-call

[andorsk]

Love this guys. I think we are good with the above.

[andorsk]

@talltree as I was going through this type:admin

[martchcl]

I have created all of the labels