Proposal: QuantEcon Enhancement Proposals (QEPs) — a lightweight process for cross-repo decisions

[mmcky]

The ask

This is a discussion draft, prompted by @jstac's suggestion in #324 that decisions like the label standardisation deserve a formal home — "QuantEcon Enhancement Proposals", similar to Python's PEPs. Please comment on the four questions at the bottom.

Why

Decisions that affect every repository, or how the whole team works — label standardisation (#324), style-guide rules, tooling standards, editorial conventions — currently happen in ad-hoc issues scattered across repos. Once closed, they're hard to find, and there's no consistent bar for what counts as "decided".

A lightweight enhancement-proposal process gives us:

• A single place to find what was decided, when, and why.
• A consistent shape for proposals — so the work of figuring out a good solution gets the weight it deserves before anything rolls out.
• A clear decision rule — so proposals actually close instead of drifting.

Prior art

Process	Model	Takeaway for us
PEP (Python)	Three types (Standards Track / Informational / Process); statuses Draft → Accepted → Final; Steering Council decides	The vocabulary (types, statuses, "rejected ideas" section) is excellent; the machinery (sponsors, delegates, editors) is far heavier than we need
MEP (MyST)	Numbered markdown files in a dedicated repo; proposed via PR; discussed on the PR	The right size — but scoped purely to a technical spec

Where QuantEcon differs from both: PEPs and MEPs govern technical specifications. Our proposals need to cover governance and editorial decisions as well as software — "how we work" proposals (like retiring status labels in favour of Draft PRs) must fit the template as naturally as technical ones.

Proposed process (deliberately minimal)

When a QEP is needed. A decision that crosses repositories or changes how the whole team works. Single-repo fixes, features, and lecture content never need one — the default for everyday work is unchanged.

Where QEPs live. A qeps/ directory in this repo (QuantEcon/meta), one markdown file per QEP, numbered sequentially (qep-0001-*.md). Since they're MyST markdown, we can render an index site later if useful — fitting, given we build everything else on MyST.

How a QEP happens.

1. Open a PR adding a draft QEP from the template; discussion happens on the PR.
2. The author sets a comment deadline (1–2 weeks, like Decision: standard GitHub label set for QuantEcon lecture repositories #324).
3. Decision by lazy consensus among Core Maintainers at the deadline; if there's no consensus, the lead (@jstac) decides or defers.
4. The merged file records the outcome — including a short "alternatives considered / rejected" section, which is where much of the long-term value lives.

Statuses. Draft → Accepted / Rejected / Withdrawn, plus Superseded when a later QEP replaces one. (No Final vs Accepted distinction — overkill at our scale.)

Template (one page).

# QEP-NNNN: Title
Author · Status · Created · Discussion link

## Summary        (3–4 sentences)
## Motivation     (what problem, why now)
## Proposal       (the actual decision being asked for)
## Alternatives considered
## Rollout        (migration, tooling, who does what)

QEP-0001. Two natural candidates: the QEP process itself (PEP-1 style, self-describing), with the label standardisation (#324) retro-written as QEP-0002 — a worked example showing the template fits a real decision we've already made.

What this is not

• Not required for normal work. If you're unsure whether something needs a QEP, it doesn't.
• Not bureaucracy. The target is the same as Decision: standard GitHub label set for QuantEcon lecture repositories #324: a 10-minute read, a deadline, and a clear close. If the process ever feels heavier than the decisions it captures, we shrink it.

---

❓ Questions

Q1 — Name. QEP (QuantEcon Enhancement Proposal) as used here, or QuEP/QUEP? Bikeshed away.

Q2 — Location. meta/qeps/ (proposed) vs a dedicated QuantEcon/qeps repo. Meta keeps it close to where decisions already happen; a dedicated repo is cleaner if we ever publish a rendered index.

Q3 — Decision rule. Lazy consensus among Core Maintainers + deadline + lead tie-break — right balance? Anything here feel too heavy or too loose?

Q4 — Scope test. Is "crosses repos or changes how the whole team works" the right bar for when a QEP is required?

[jstac]

Thanks @mmcky !

Q1 QEPs is neat
Q2 /meta/qeps seems natural
Q3 Sounds like the right balance
Q4 Yep, sounds right to me.

[mmcky]

Thanks @jstac -- my thinking over night is favouring QuantEcon/qeps (rather than meta) -- but not strongly aligned either way.

These days with lower infrastructure costs, I tend to lean towards specialised repos as that leaves the repo focused, gh-pages to host a qeps page (and we link to it), and the Issues register can be setup with a qeps discussion template that then feeds into a PR (without the noise).

The only real downside is remembering we have qeps but I'd document the process in the manual.

[jstac]

Sure @mmcky , that's fine by me!