Proposal: Design-first features and a rolling roadmap

[ascorbic]

Every new feature would be designed and accepted before its implementation PR opens. A narrowly-scoped feature would use a short feature plan. A broader or harder-to-reverse change would use a full request for comments (RFC). Both would be reviewed as design PRs, and merging the design PR would accept the design and permit implementation.

"Ideas" Discussions currently mix early requests, concrete proposals, and offers to implement a feature. Approving an idea can establish that the feature is wanted without settling how it should work. The remaining design decisions then move into the implementation PR, where each change requires code and tests to be revised as well.

This proposal gives requests, designs, implementations, and roadmap priorities distinct purposes. Project roles, maintainer authority, and merge rights are covered by the separate governance proposal.

Process at a glance

There are two feature paths:

Narrowly-scoped feature → feature-plan PR → implementation PR

Broader or harder-to-reverse feature → "Ideas" Discussion → RFC PR → implementation PR

• An "Ideas" Discussion is optional before a feature plan and required before an RFC. It establishes the problem and demand before the detailed RFC is written.
• The design PR settles how the feature will work. Every feature requires one, and merging it counts as approval of the design.
• The implementation PR delivers the accepted design. Every feat: PR must link its merged design PR.

Roadmap placement is a separate decision. Accepting a design permits implementation but does not make the work a current project priority or promise it for a release.

Changes that do not introduce a feature can normally go directly to an implementation PR. These include i18n:, fix:, chore:, docs:, and test: changes, plus behaviour-preserving refactor: and perf: changes.

Why design comes first

Agentic coding tools have changed where feature development spends its time. Once a feature has a complete and internally consistent plan, implementation can be quick. The difficult work is deciding the behaviour, interface, data model, compatibility constraints, failure handling, security boundaries, user experience, and tests.

Review is most useful while those decisions exist as a design and remain inexpensive to change. Resolving them inside an implementation PR requires repeated changes to code and tests. A long-lived branch also becomes stale, conflicts with main, and can stop fitting the codebase as other work lands.

The accepted design should be detailed enough that implementation does not reopen ordinary product or architecture decisions. Implementation review still verifies correctness, security, compatibility, tests, and conformance with the design. If implementation exposes a flaw in the plan, the design should be amended explicitly rather than changed implicitly through code review.

Prototypes remain useful during design. Contributors are encouraged to test feasibility, interfaces, performance, or interactions locally or in a fork, then link the findings from the design PR. Prototype code should not open as an implementation PR (including draft PRs) against EmDash before the design is accepted.

Settling the design first also avoids wasting CI on implementation revisions that may be rewritten or discarded.

An accepted design also gives human reviewers and EmDashBot something to review against. The reviewer guidelines can require EmDashBot to compare the implementation with the linked design and report omissions, divergences, unplanned scope, and missing tests.

Feature plans and RFCs

Feature plans

A feature plan is the normal route for bounded, additive functionality within the existing architecture. It is assumed that the person opening the plan is also proposing to implement it. The plan should explain:

• The problem and concrete user case.
• The behaviour a user or integrator will observe.
• The goals and non-goals.
• Any effect on interfaces, configuration, stored data, or compatibility.
• Important errors and edge cases.
• How the behaviour will be tested.

A feature plan does not require a separate Discussion. It can link to an issue, earlier Discussion, or roadmap item when one exists, but the feature-plan PR can itself establish the problem and proposed design. It can merge after approval from one human maintainer other than the author and has no fixed minimum review period.

The boundary does not need to be decided perfectly before writing begins. A contributor can start with the shortest plausible plan. If review reveals RFC-level risk, the project pauses acceptance and opens an "Ideas" Discussion. The proposal can then expand into a full RFC in the same PR rather than starting again.

Full RFCs

A full RFC is required for changes that affect public APIs, stored data, plugin surfaces, security boundaries, defaults, backwards compatibility, several packages or runtimes, critical-path performance, privileged supply-chain systems, breaking changes, or another decision that would be expensive to reverse.

The RFC process starts with a public "Ideas" Discussion to establish the problem, demand, and broad scope before detailed design begins. The resulting RFC adds the architecture, alternatives, failure handling, versioning, migration, security, performance, rollout, and rollback detail relevant to the change. It requires a named champion and maintainer sponsor, support from at least two maintainers, and acceptance by the Project Lead after a public review period. The proposed default review period is seven days.

Design PRs and acceptance

A design PR adds or amends a feature plan or RFC. They should not contain any code. Feature plans and RFCs should live together under proposals/ and use descriptive filenames. They do not need manually allocated proposal numbers. The GitHub PR number identifies the design review and acceptance event after the PR is opened.

A dedicated design PR template will distinguish proposal work from implementation work. Contributors are encouraged to open draft design PRs when early feedback would help. A draft can contain unresolved questions or have no sponsor yet, provided it says what remains open.

Merging the design PR means acceptance. The merged proposal becomes the plan of record; the design PR should not remain open during implementation. A later design PR can amend, supersede, or withdraw it.

Every feat: implementation PR must link a merged design PR in the EmDash repository. This rule applies equally to maintainers, the Project Lead, employees, and external contributors. There is no routine design-not-required exemption for features. If a PR is classified incorrectly, a maintainer can correct its type.

Automation should verify the design link and use lightweight checks for design-only PRs. The exact templates, proposal metadata, labels, path rules, and checks belong in the implementation PR rather than this Discussion.

EmDashBot should load the accepted design when reviewing an implementation and report where the code diverges from it. Its report remains review evidence; a human maintainer retains approval authority.

Indicative lifecycles

The process should remain proportionate to the change.

Small feature

An issue or maintainer sponsor already establishes the need.

Short feature-plan PR → one maintainer approval → implementation PR

No separate Discussion, fixed comment period, or roadmap entry is required.

Complex feature

The change introduces a public contract, stored data, security boundary, or architectural decision.

"Ideas" Discussion → draft RFC and prototypes as needed → public acceptance review → one or more implementation PRs

Roadmap priority is decided separately. An accepted RFC does not automatically become current work.

Roadmap discovery

The project has selected an important problem but has not chosen a solution.

Roadmap discovery → research, Discussions, and prototypes → feature plan or RFC → implementation

The roadmap records a commitment to investigate the problem, not acceptance of a particular solution.

Requests and triage

Ideas Discussions remain the request inbox. A requester should describe the problem and use case but does not need to design or implement the solution. The Discussion form should separately ask whether the author is requesting the capability, offering to champion the design, or offering to implement it after acceptance.

The Project Team should keep requests understandable by classifying them, connecting duplicates and related work, asking for missing use cases, and surfacing candidates to maintainers. Triage does not accept a design or commit the project to implementation. Detailed responsibilities and closing rules belong in the triage documentation.

A request does not become a roadmap item merely because it exists. It can remain open until it is implemented, superseded, declined with a public reason, or found to be outside the project's scope.

Rolling roadmap

The roadmap covers project-led work: initiatives the project has chosen to prioritise and coordinate. It is not a backlog of every idea or accepted design, and it is not an implementation gate. A contributor who brings an accepted design and intends to implement it can proceed immediately without roadmap placement.

An accepted design without an implementer remains available in the proposals index. It enters the roadmap only if the project later decides to drive the work.

Tracking project-led work

Each project-led initiative has a public tracking issue and an item in the public GitHub Project. The issue is the canonical record for the intended outcome, why the project is prioritising it, its champion and maintainer sponsor, the next step, and links to relevant Discussions, design PRs, and implementation PRs. One initiative can produce several proposals and implementations.

The Project records two separate dimensions:

• Horizon shows when the project aims to advance the initiative.
• Stage shows what is currently happening.

The horizons are:

• Now: actively being advanced.
• Next: intended within roughly the next six months.
• Later: an aim for roughly six to twelve months from now.
• Unscheduled: project-led work with no target window.

The stages are Discovery, Design, Ready, Building, Paused, and Shipped. A roadmap initiative can begin in Discovery before a solution is ready to specify. Its tracking issue links the research and Discussions until a feature plan or RFC is ready. Later design and implementation PRs link back to the same issue.

Now and Next items require an active champion, a maintainer sponsor, and a defined next step. The Project Lead makes the final decision on roadmap placement after public reasoning and consultation. GitHub remains the decision record.

Direction and timelines

The horizons are planning signals rather than release promises. Exact dates or target releases should appear only when delivery is sufficiently certain.

ROADMAP.md provides a short rolling 12-month summary of the outcomes the project is aiming for, grouped by horizon. It states when the roadmap was last reviewed and links each outcome to its tracking issue and the live GitHub Project. The Project holds detailed current status rather than duplicating it in the document.

The roadmap should be reviewed every few months and whenever priorities materially change. Decisions can still happen asynchronously between reviews.

Transition

If this proposal is accepted, follow-up PRs will add the proposal documentation and templates, implement the design-link check, update EmDashBot's reviewer guidelines, and document the public roadmap and triage process. Existing feature PRs will receive a published transition rather than being closed automatically: settled designs can be recorded retrospectively, while PRs with unresolved design questions can move those decisions into a proposal.

Feedback requested

Feedback is particularly useful on:

• Whether the feature-plan and full-RFC boundary is based on the right risks.
• Whether one approval is enough for a bounded feature plan and two are enough for a full RFC.
• Whether seven days is the right default review period for a full RFC.
• Whether the strict design requirement for every feat: PR creates any cases the classification rules cannot handle.
• Whether Now, Next, Later, and Unscheduled provide useful direction without implying firm delivery dates.
• Whether a tracking issue and GitHub Project item provide enough context for each project-led initiative.
• How existing open feature PRs should be handled during the transition.

After public feedback and consultation with the Project Team and Maintainers, the Project Lead will post a decision summary and open the follow-up PRs needed to implement the accepted process.

[MA2153]

It requires a named champion and maintainer sponsor, support from at least two maintainers, and acceptance by the Project Lead after a public review period.

Worth clarifying if the sponsoring maintainer or the Project Lead can count against the two-supporting-maintainers quota.

The other thing is clarifying how conflicting RFCs are handled, since they can be merged without being implemented for a while. If one RFC gets merged, and another RFC that touches some of the same systems also get merged, the latter could affect some aspects of the design that the earlier RFC didn't account for, or could make its end-goal no longer relevant, etc.

Otherwise this looks good to me!

[ascorbic]

Good points. I'll clarify in the text, but I think for the first question I'd say no, because the Lead already gets a veto.

For conflicting RFCs, I think we just need to say that conflicting RFCs must be clarified and rescoped before they're merged. A design PR can edit existing RFCs too (which is reviewed at the same time)

[danielmlr]

Thanks Matt!
Design first makes a lot of sense, and merging the design PR as the "yes" is much clearer than a label.
A few things I noticed while thinking about how this works day to day:

1. Ideas still have no answer time. Right now there are 282 open Ideas. 145 of them have no comment at all, 132 haven't had any activity in two months, and 41 new ones came in last week alone. The proposal explains clearly how a design gets accepted, but nothing says when an Idea gets its first reply. Could we set a rough target, say a first sorting within a few weeks (needs info, candidate, better as a plugin, out of scope)? The Project Team could carry that.

2. Ideas that were already approved. 15 open Ideas carry Approved for PR from the old process. Do they now just need a feature plan, or do they start over? And does the label stay?

3. Closing the loop. The proposals index records the implementation PRs, but nothing closes the original Ideas Discussion when the feature ships. A "shipped in x.y" comment and a close, as part of the implementation PR or the release, would keep the list honest.

4. The Roadmap Project. Who can update Stage and Horizon? If only admins can, it'll fall behind quickly. Write access for maintainers or the Project Team would help.

5. The next major. The deprecations kept through 1.x in chore!: remove deprecations before 1.0 #3519 (the legacy plugin capability names, the marketplace option and a few more) are the natural list for the next major, but they don't really fit Horizon and Stage. Maybe one tracking issue for them, linked from ROADMAP.md?

[ascorbic]

Good questions!

1. we're not going to start introducing SLAs or anything. The new design PR process should make it easier to clear Ideas discussions: in most cases they will just need sorting rather than detailed discussion (i.e. is a design PR welcome, is it better as a plugin or is it out of scope). We can set up these labels. A good addition to the docs could be saying that regular calls can be used to evaluate them.
2. We'll just rename the label to "design PR welcome" or something, and they can then proceed as usual with a plan
3. we should automate this. We can add a "status: implemented" that's set by the last implementation PR, and when it's merged the bot can close the discussion.
4. "stage" should be updated by the proposal champion. If I can I'll give project team write access. Horizon is a project lead decision though.
5. yes, a new tracking issue for deprecations. We should ensure that we are disciplined in adding things to that list when the design PR merges. Anything that deprecates something will almost always need an RFC.