TypeSpec Repo Issue and PR orgranization

[timotheeguerin]

We have a bit of a mess in our labels and pr naming is inconsitent/hard to review

Labels

Area labels

• compiler:core, compiler:emitter-framework, etc.
• emitter:client:<lang>
• emitter:service:<lang>
• emitter:openapi, emitter:grpc, etc.
• lib:http, lib:rest, lib:openapi, lib:tcgc
• tspd
• meta:website, meta:blog
• ide, ide:vscode, ide:vs
• eng General eng sys relevant to the entire repo

Kind labels

• bug, feature, epic, docs

Process label

• needs-triage - Automatically added on issue creation

Needs author feedback flow:

Current:

• needs-author-feedback - Someone needs to put this label explicitly
• no-recent-activity - after 1 week
• close after 2 weeks
• needs-team-attention Added back if user reply

Proposed:

• needs-author-feedback - Someone needs to put this label explicitly
• close after 2 weeks
• needs-triage adds needs-triage back if user reply

Design labels

• design:needed, design:proposed, design:approved

Breaking change labels

• breaking-change, deprecation

Cleanup labels

Let's delete unused labels. Let's also delete low value labels if possible.

For example:

• add-to-typespec-project - do we need this label? If so, can we remove it automatically once the issue has been added?
• customer-reported - is this valuable?
• client-emitter-migration - temporary label during the migration we should remove and move remaining issue in the correct area
• API Stewardship Board - Not sure what this means?
• DPG Impact - At the very least needs to be reworded to be useful for non-Azure to understand?
• Epic: xyz Feel like we should use task list/sub issue or project for this instead

Issue & PR naming convention

Issue titles are just issue titles without metadata, so no prefixes, suffixes, or the like. Metadata exists in labels. This will ensure the smoothest possible experience with Chronus and other tooling, at the expense of slightly less useful commit descriptions.

Existing labels

Keep

• bug
• good first issue
• needs-triage
• needs-author-feedback

Rename

• documentation -> meta:docs

• Client Emitter:

  • emitter:client:<lang> -> emitter:client:<lang>

• enhancement -> feature

• Design: Needed -> design:needed

• Design: Proposed -> design:proposed

• Design: Accepted -> design:accepted

• Service Codegen:

  • emitter:service:<lang> -> emitter:service:<lang>

• IDE -> ide

• Epic -> epic

• gRPC -> emitter:protobuf

• Json Schema -> emitter:json-schema

• Infrastructure -> eng

• Contains Breaking Changes -> breaking-change

• Contains Deprecations -> deprecation

• add-to-typespec-project -> triaged:core (can we remove after it gets added to the project, can we remove long term?)

• Client Emitter Migration -> eng or emitter:client:X

Remove

• :pushpin:

• Required for DPG 2.0

• Post DPG 2.0

• WS: Svc Partner Adoption

• WS: External Developer Adoption

• WS: Language Completeness

• Epic: Cadl User Guide

• Epic: Cadl language developer documentation

• Epic: Change management & release process

• Epic: Language verification & testing

• Epic: Tooling help for decorators

• Epic: Emitter Framework

• Epic: Side-car

• Epic: Projections to stable

• Epic: Sub-typing

• Epic: Refactor resource framework out of Rest lib

• Epic: Unification of Templates etc

• WS: Process Tools & Automation

• WS: Code Generation

• Epic: Cadl Metadata

• duplicate

• needs-team-attention

• dependencies

• help wanted

• question

• wontfix

• Needs Estimate

• Needs Triage

• customer-reported

• no-recent-activity

• needs-customer-feedback

• Graph Impact

• DPG Impact

• CLI/PSH Impact

• Public Beta

• OpenAI

• Potential Breaking Changes

• breaking-change-approved

• MQ

• API Stewardship Board

• Figure if we can define this list in a file

• Document labels, processes to CONTRIBUTING.md

• Issues:

  • Always expect an area
  • Usually expect an impact

• PR:

  • Should be able to assign area(s) automatically
  • Don't need the impact?

Colors

compiler: -- typespec brand color (dark purple) lib: -- light purple ide:* -- mid purple

emitter:client: -- light yellow emitter:server: -- dark yellow/gold emitter:* -- mid yellow

eng: light blue (azure brand color) meta: mid blue tspd: dark blue

bug, feature, epic, docs -- light grey

needs-triage -- light red triage-accepted -- grey

design:needed -- light green design:proposed -- mid green design:approved -- dark green

breaking-change: mid red deprecation: dark red

[m-nash]

related to https://github.com/microsoft/typespec/issues/3157

[m-nash]

@timotheeguerin is the suggestion here every issue has at least one label from Area labels and one label from Impact labels? Or what exactly should a good issue look like?

[bterlson]

I think it's fair to say almost every issue should have an area label and an impact label. Issues in the meta and eng area may not have impact labels I suppose.

[timotheeguerin]

Yeah I agree I think every issue should get triaged into at least an area(maybe more) and have an impact(for most) For PRs we should be able to automatically add the area labels and that could be 1,2+ don't know if its necessary to have the impact label on the PR as well.

[markcowl]

Some comments

• change add-to-typespec-project to triage-accepted. We actually need this label to drive automation for now, but can remove the label after issues are copied into the project.
• DPG Impact: we like to track impacts of core and library changes on various audiences, particularly DPG for client emitters and third-party for openapi3 changes. We track this in the project using a field, so I think we can remove this as a label, if we agree to use the project to track internal matters like this
• Epic: we can just remove, IMO, we have epics in the project
• customer-reported is probably obsolete now.