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.

[Chihiro2000GitHub]

Thanks, @mmcky, for summarizing the discussion.

I'm happy with the proposed resolutions on all three questions.

I don't have strong views on the detailed label design, since I'm still getting used to GitHub workflows and have not used this kind of label system extensively before.

But from my perspective as an RA, they all look reasonable to me.

As for the third question, this feels especially relevant to me, since I've been working on the NumPy migration and opening many PRs. I'm comfortable following the Draft PR / Ready for review / Review request convention instead of using status labels.

So I'm happy to go along with the proposal.

Thanks again!

[shlff]

Hi @mmcky thanks for the thorough proposal and for summarising the discussion. I support the updated scheme.

Q3: yes.

Q2: no strong views on the candidate repos; I'll leave that to those who work on those repos.

Q1: I wouldn't add or remove any labels from the lecture-repo set at this stage, but few small guide level clarifications might help:

1. Clarify the “unlabelled” rule: Worth stating explicitly in the guide that "no labels at all" and "no priority label" are different states. A bug with no priority label has been triaged and is normal priority, while a completely unlabelled issue still needs triage. The preamble and the priority section together imply this, but a single explicit sentence would help new contributors.
2. Add one line on discuss exit: Without a closing convention, discuss threads could drift open indefinitely. A short guide note would help: once a thread reaches a conclusion, either summarise the decision and close, spawn a concrete follow-up issue, or escalate to a QEP if it crosses repos or changes team workflow.

One optional process thought, probably for #325 rather than this rollout: a meta-only qep-candidate label could make possible QEPs easy to find. But I would not let that block this label standardisation.

Thanks.

[mmcky]

Adding context from the automation side — I've been wiring the org activity reports + quantecon.org/news drafts to read these labels, so a couple of notes plus one Q1 proposal.

This standardization isn't just tidiness — it directly sharpens the automated reporting. While building impact-ranking for the weekly highlights I found the reports were keying off labels that don't exist (priority: high, feature, chore, docs — none are used anywhere; the real names are high-priority, enhancement, documentation). So a high-priority PR currently gets no boost. The proposed set fixes exactly this and gives the reporting a stable contract.

How the reports / news drafts consume the proposed labels, for visibility:

Proposed label	Effect in the activity reports / news
new-lecture	Headline signal — leads the report / a news post
enhancement	Reader-facing work — surfaced above the fold
high-priority	Importance boost — surfaced above the fold
maintenance	Reader-invisible upkeep — demoted below content
documentation	Mild demotion (repo meta, not lecture content)
dependencies / automated / build-failure / broken-links	Filtered out as bot/mechanical noise

Q1 — one addition: keep infrastructure as a distinct Type label (sibling to maintenance)

The proposal folds infra into maintenance ("work a reader never sees"), but for the team — who are the audience of the internal activity report, not lecture readers — those are two different things:

• infrastructure — substantial engineering a teammate wants to know shipped: a CI pipeline migration, build-system change, new automation, deploy rework.
• maintenance — routine housekeeping: style/formatting, env & dependency bumps, small upkeep. Invisible churn.

The cleanest evidence they're distinct: the activity reports already treat them differently — infrastructure surfaces as notable, maintenance is demoted below content. Fold them together and "we re-architected CI across the lecture repos" sinks into the same bucket as "bumped a pin." And it matters most exactly where the core-16 lands hardest — the software/tooling repos, which are substantially infra work.

Proposed spec (a Type label, one-per-issue like the others, so the boundary stays clean at triage):

Field
Name	infrastructure
Description	Substantial CI / build / deploy / tooling / automation work
When to use	Engineering a contributor should know about. Rule of thumb: would a teammate want to know this shipped? — infra yes, maintenance no. Use instead of maintenance
Scope	Core set (all repos)
Colour	something distinct from maintenance 🟨 — note infrastructure already exists on some repos (e.g. lecture-python.myst), so this is keep-don't-merge, not a brand-new label

Two more notes

• new-lecture is the single most valuable label for the reports — it's the marquee event we headline — so it's worth applying consistently even ahead of the rest. (The drafter keys off the hyphenated new-lecture.)
• Retiring the status labels (in-work/ready/review) has zero impact on the reporting — it never read them. +1 on Q3.

One caveat for qe gh labels sync: many repos carry legitimate bespoke labels (jax-conversion, colab, site-refresh, reading-group-*). Make the sync additive — guarantee the standard set, but don't blanket-prune the extras (rename-in-place, à la linkchecker → broken-links, is exactly right). A full prune would wipe useful local labels.

The labels the reporting consumes are catalogued in reports-activity (docs/labels.md, QuantEcon/reports-activity#60), tracking whatever this issue settles on.

[quantecon-services]

@mmcky — scheduled reminder to check this thread. Summary below.

Issue #324 — Standard GitHub label set for QuantEcon lecture repos

Deadline: Wednesday 17 June (tomorrow). Rollout the following week.

Original proposal

18 labels across 6 groups: Type, Priority, Editorial/Workflow, Community, Automation (bot-only), and Meta closing outcomes. Unlabelled = needs triage, normal priority. The 3 questions: Q1 (label set), Q2 (which repos in first rollout), Q3 (retire status labels in favour of native GitHub: Drafts, "Ready for review", review requests).

What's been agreed

• Q3: Unanimous — retire in-work, ready, review, blocked as labels; use Draft PRs + native review state instead. Only do-not-merge survives.
• Community label spacing: Keep good first issue and help wanted with spaces — GitHub's Contribute-page algorithm requires the exact spaced names. All QuantEcon-owned multi-word labels stay hyphenated.
• Add discuss (raised by @jstac, +1 by @mmcky): core label for open-ended team deliberation, distinct from question (which seeks a single answer). Reuses meta's existing pink #f904a0.
• Recolour documentation to tan #b08968 (@xuanguang-li, +1 @mmcky): separates it from the blue new-lecture/enhancement family.
• Don't add blocked: native GitHub issue dependencies (GA since Aug 2025) cover the issue case; Draft + "Blocked by #N" comment covers PRs.
• Proposed count: 19 labels (core 17 + new-lecture + editor for lecture repos; org default = core 17).

Open / needs your attention

Q1 — infrastructure label (raised by @mmcky in the most recent comment, Jun 16): Proposes splitting maintenance into two Type labels:

• infrastructure — substantial CI/build/deploy/automation work a teammate wants to know shipped
• maintenance — routine housekeeping, invisible churn

Evidence: the activity reports already treat these differently (infrastructure surfaces as notable, maintenance is demoted). The label already exists on some repos (e.g. lecture-python.myst). This would bring the set to 20 labels. Needs a decision before the Jun 17 close.

Q2 — candidate repos (@mmcky's update summary, Jun 13): No one has ticked any of the five candidates yet:

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

First rollout defaults to the confirmed six unless someone ticks one by tomorrow.

Guide clarifications suggested by @shlff (Jun 15) — for the labels guide, not a blocker on rollout:

1. Explicit sentence: "unlabelled" (no labels at all) ≠ "no priority label" (triaged, normal priority).
2. discuss closing convention: summarise decision and close, spawn follow-up issue, or escalate to QEP.

qe gh labels sync reminder (@mmcky, Jun 16): Make the sync additive — guarantee the standard set but don't prune bespoke local labels (e.g. jax-conversion, reading-group-*). Rename-in-place (e.g. linkchecker → broken-links) is the right approach.

Nothing blocking rollout

Consensus on Q3 is unanimous. Q1 just needs the infrastructure call. Q2 can default to the six confirmed repos if no one ticks candidates today.