Decision: standard GitHub label set for QuantEcon lecture repositories

[mmcky]

The ask

Please review the proposed standard label set below and comment on the three
questions at the bottom — ideally by Wednesday 17 June so we can roll out the
following week.

This issue is decision-only and closes when we agree. Full rationale,
the org-wide audit, and implementation tracking live in #323 — nothing here
needs reading beyond this page to respond.

Proposed label set (18)

Unlabelled = "needs triage, normal priority" — nothing must be labelled.
Colour carries meaning: priority is a heat scale, automation is quiet grey.

Type — what kind of work? (one per issue, at triage)

Label	Colour	Description	When to use
bug	🟥 #d73a4a	Something is wrong or broken in a lecture or build	The lecture is incorrect: wrong maths, erroring code, broken rendering
enhancement	🟦 #a2eeef	Improvement to existing material	Better exposition, new exercise, improved figures
new-lecture	🟦 #0537E9	A new lecture (the marquee outcome)	Brand-new lecture — proposed, in progress, or shipped. Use instead of enhancement
documentation	🟦 #0075ca	Repo docs and contributor meta	READMEs, CONTRIBUTING — about the repo; lecture content is never documentation
maintenance	🟨 #fbca04	Housekeeping: tooling, infra, style, environments	Work a reader never sees; "rendered lectures look identical after"
question	🟪 #d876e3	A question or discussion thread	Swap for a work type once it becomes agreed work

Priority — heat scale (unlabelled = normal)

Label	Colour	Description	When to use
high-priority	🟧 #d93f0b	Address soon	Published content visibly broken; build blockers. Label only the outliers
low-priority	🟩 #c2e0c6	Nice to have, no time pressure	Agreed work that's fine to sit; "someday" ideas. No medium — default is the middle

Editorial & workflow

Label	Colour	Description	When to use
editor	🟩 #0e8a16	Requires editor review — final sign-off	Apply at handoff after team review; editor's queue = org:QuantEcon label:editor. Remove on sign-off
do-not-merge	🟥 #b60205	Must not be merged yet	May look mergeable (even approved) but held: pins, experiments, cross-repo timing

Community (GitHub-canonical names)

Label	Colour	Description	When to use
good first issue	🟪 #7057ff	Self-contained, friendly to newcomers	Only when genuinely self-contained with clear acceptance criteria
help wanted	🟩 #008672	Outside help welcome	Including domain (econ/math) expertise — say what's needed in a comment

Automation — applied by bots, not humans (quiet grey)

Label	Colour	Description	When to use
automated	⬜ #ededed	Opened by a bot or scheduled workflow	Every bot issue carries this + exactly one diagnostic below
broken-links	⬜ #dddddd	Link checker found dead links	Applied by action-link-checker
build-failure	⬜ #cccccc	Execution, build, or warnings failure	Applied by build/warnings checks
dependencies	⬜ #bdbdbd	Dependency or environment update	The single Dependabot label (replaces github_actions / conda)

Meta — closing outcomes

Label	Colour	Description	When to use
duplicate	⬜ #cfd3d7	Already tracked elsewhere	On close; link the survivor
wontfix	⬜ #ffffff	Decided not to act	On close, with one sentence why

What we deliberately DON'T label

in-work → Draft PR · ready → "Ready for review" · review → review
requests · blocked/on-hold → Draft + link the blocker · medium-priority →
no label · project labels (reading-group-*) → Milestones · per-tool labels
(colab, …) → build-failure.

Scope (summary)

• Lecture repos get all 18. Software/tooling repos later get the core 16
  (everything except new-lecture + editor), which also becomes the
  org-level default set for new repos.
• Not touched: meta (keeps discuss/project/education), translation
  forks (translate:*), *.notebooks build repos.
• Migration renames labels in place (e.g. linkchecker → broken-links), so
  existing issue/PR history is preserved.

---

❓ The three questions

Q1 — The set. Any label you would add, remove, or rename? (Names, colours,
and descriptions above are the proposal; say what you'd change.)

Q2 — Which lecture repos are in? Confirmed: lecture-python-intro,
lecture-python-programming, lecture-python.myst,
lecture-python-advanced.myst, lecture-dp, lecture-jax.
Candidates — tick any that should also be in the first rollout:

• lecture-julia.myst
• lecture-datascience.myst
• lecture-stats
• continuous_time_mcs
• lecture-wasm

Q3 — The one behavioural change. Status labels (in-work, ready,
review, blocked) are retired in favour of native GitHub: open PRs as
Drafts while working, click "Ready for review" when done, use review
requests for review state. Only do-not-merge survives as a label. Are you
comfortable committing to this convention?

---

Background, full rationale per label, the org-wide audit (this is the 4th
unification attempt — #178, #290 will be closed against the outcome here), and
implementation tracking: see #323. Tooling to apply the result is ready
(qe gh labels sync, QuantEcon/cli).

[jstac]

This all looks good to me. Many thanks @mmcky . Great to standardize.

I notice this lecture has 'discuss', which seems useful --- but isn't included in the new set? I guess it's similar to 'question'.

[longye-tian]

Hi @mmcky

Thanks for standardizing them. They looks great!

I agree with all three.

I noticed that good first issue and help wanted label are not connected by - as others like broken-lines etc.

I don't know what the norm is in labelling in github but they both looks great to me.

Best,
Longye

[xuanguang-li]

Thanks, @mmcky, that looks great.

• Q1: I think the colors used for the new-lecture and documentation labels are a bit too similar. Maybe we could increase the contrast between them.
• Q2: I left it blank since I haven't worked on those repos.
• Q3: I agree.

[mmcky]

thanks @jstac

I notice this lecture has 'discuss', which seems useful --- but isn't included in the new set? I guess it's similar to 'question'.

Ah -- good point! this proposal is primarily focused on lecture-* repos. I was thinking of focusing on domain and establishing repo families (based on QuantEcon naming conventions) to establish a focused set of labels.

I thought an action-translation repo won't need many of the lecture-.* labels.

+1 for discuss

[mmcky]

thanks @longye-tian

I noticed that good first issue and help wanted label are not connected by - as others like broken-lines etc.

I agree I think standard is good good-first-issue and help-wanted. I think the space versions come from the standard GitHub library but my thinking is no white space.

[mmcky]

I think the colors used for the new-lecture and documentation labels are a bit too similar. Maybe we could increase the contrast between them.

thanks for the feedback @xuanguang-li. +1 from me on changing the colour for documentation as new-lecture and enhancement are "new" things to be published on a lecture, while documentation is a tier 2 concern.

[mmcky]

I think another good candidate to add would be blocked (red) but I need to think through how it is different to do-not-merge

[mmcky]

Update — where the discussion stands

Thanks @jstac, @longye-tian, @xuanguang-li for the quick feedback. Consensus is strong, and a few specific points refine the set. Below is where things stand so far — these are proposed resolutions, not yet final. The thread stays open for comment until Wednesday (17 June); I'll fold in anything further before locking the set and starting rollout.

Proposed resolutions to the feedback

1. Add discuss (raised by @jstac) — proposed as a core label, since deliberation happens on every repo, not just lectures. It would reuse meta's existing discuss colour (#f904a0) for cross-repo continuity. On @jstac's "isn't it similar to question?" — yes, so the two are split cleanly:

• question — someone needs an answer / clarification (terminal state: answered).
• discuss — open-ended team deliberation or a decision to be made (no single right answer).

2. good first issue / help wanted — proposing we keep the spaces (re: @longye-tian's consistency point). I looked into hyphenating them, but the spaced names are load-bearing: the exact label good first issue (with spaces) is what GitHub's algorithm uses to populate a repo's Contribute page and surface approachable issues org-wide. The hyphenated good-first-issue is a repo topic — a different namespace, not the label. Renaming would lose newcomer-discovery for no functional gain, so the inconsistency is deliberate: these two belong to GitHub. Every multi-word label we own stays hyphenated.

3. Recolour documentation (@xuanguang-li, +1 from me) — moving it off blue to tan #b08968. enhancement + new-lecture are both "new content to publish" and stay in the blue family; documentation is a tier-2, about-the-repo concern, so a distinct hue separates it clearly from new-lecture.

4. blocked — leaning not to add it (my earlier question vs do-not-merge). The distinction is real — blocked is an involuntary external dependency and applies to issues too, vs do-not-merge's voluntary hold on a mergeable PR. But GitHub now has native issue dependencies ("Mark as blocked by", generally available since Aug 2025, also surfaced in the CLI). That covers the issue case a label was for, records what blocks what, and avoids a second red clashing with do-not-merge. So the proposal is: native dependencies for issues, Draft + "Blocked by #N" for PRs — keeping the Q3 "drop status labels" direction intact. Open to pushback if anyone wants a visible badge.

Current standing on the three questions

• Q1 (the set): with the above, 19 labels = core 17 + the lecture pair (new-lecture, editor). Org-level defaults would be the core 17. Still open for additions/removals.
• Q2 (repos): no candidate repos ticked yet, so the first rollout would target the confirmed six. The five candidates (lecture-julia.myst, lecture-datascience.myst, lecture-stats, continuous_time_mcs, lecture-wasm) remain easy to add — tick any you'd want in the first wave.
• Q3 (Draft PRs): confirmed by everyone who's replied so far.

The updated draft schema and full per-label rationale are in QuantEcon/cli (src/qe_cli/data/labels.yml, docs/labels-guide.md) if you'd like the detail; rollout is tracked in #323. Please add any comments by Wednesday.