Making technical proposals easier to find, track, and comment on

[Dieterbe]

today, technical proposals are simply an issue
Suggestion: make them a a PR which adds a file to docs/proposals/<proposal-name>.md ( or docs/rfc/<number>-<name>.md which is also a common scheme in other projects)

Here are some benefits:

1. it makes all proposals easier to find. For example querying for "proposal:" does not seem to be a reliable way to see what all the current proposals are. Both because the query matches more things that include the word "proposal", and also because proposals may be made with the wrong title
2. it makes it easier to comment on specific parts, since in a PR you can add comments under specific lines and files. Whereas having a discussion thread can get unorganized faster
3. you could merge the PR once the proposal has reached a certain point of maturity (e.g. generally accepted, but could use further refinement). Further refinements or reworks can come in followup PR's from other community members, or from Martin, and could invite more discussion
4. a proposal could include changes to other docs such as ADR's or plans (in the same PR)
5. having (accepted) proposals in the repository makes it easier to work on them offline. (not sure if Martin cares about this?)

Alternative solutions:

• ask users to make issues like today, but give them a label such as "proposal". This fixes the first point. Labels also allow further classification (e.g. "proposal", "proposal-accepted", etc)
• use something like google docs. would fix the 2nd point (it works very well for commenting and revising on specific parts of a text document) but seems more clunky of an overall workflow and misses all the other benefits.

[Brikas]

Are there any existing respectable repos adopting this method? 🤔

What distinguishes a 'technical proposal' from a feat request or issue?

It seems to add a bunch of rigidity and learning curve for contributions. And for the scale of contributions at Tine, 'comments under specific lines and files' on proposal.md docs may be over-engineering compared to simply quoting a line in a discussion/issue comment. I'd see this making sense for big repos like the linux kernel etc.

Regarding the first point -> A GitHub/AI bot auto-classifying issues for any label is a solution that avoids 'ask user' friction and may be more accurate.

Just voicing my thoughts, feel free to pushback.

[Dieterbe]

What distinguishes a 'technical proposal' from a feat request or issue?

a cross-cutting or consequential design decision where alternatives, trade-offs, and a durable record are useful. Something that lays out a concrete technical approach. e.g. storage architecture, sync, plugin model, or a significant query-language change.

Are there any existing respectable repos adopting this method? 🤔

Yes, this approach is quite common. Some examples:

• Rust RFCs: a substantial proposal starts as a PR adding a Markdown file under text/; discussion and revisions happen on that PR; merging it makes the RFC active.
• React RFCs: essentially the same model.
• Electron RFCs: A proposal is a PR adding a Markdown document; when accepted it is merged, and later changes to the accepted RFC happen through follow-up PRs.
• Kubernetes uses KEPs (“Kubernetes Enhancement Proposals”), also submitted and maintained through PRs.
• Python has "PEP's" (python enhancement proposals), they have a bit more ceremony and governance because it's obviously a big project, but at the core, it's the same simple process

[Brikas]

@Dieterbe thanks for adding examples