Hi It makes sense. I think Mick talked more specifically about governance document (like the graduation criteria/maturity matrix).
Some projects are using PR with md for proposals (we do that in ActiveMQ for instance). The website already have a page listing the issue with the proposal label. So we can extend with merged/closed PRs. I like the idea. As I’m working on the Delegation Proposal, I propose to use this one as illustration. Especially to deal with images and such :) Thanks for sharing the idea ! Regards JB Le dim. 15 févr. 2026 à 14:42, Robert Stupp <[email protected]> a écrit : > Hi all, > > Mick brought up a very good point [1] about the use of Google Docs for > proposals. > > Very simplified, our current proposal process is > - a contributor creates a Google Doc > - the proposal is introduced on [email protected] > - discussion happens on both the Google Doc and the dev@ mailing lists > > Google Docs are a great vehicle for collaboration. Just, I think the > commentary functionality there is a bit odd. > There's also a "disconnect" (or "media break" if you prefer that term) > between the discussions that actually count and those that do not (think: > "If it did not happen on the mailing list, it never happened.") > The valuable information in those Google Docs gets "lost", as there's no > more direct relationship from the code or documentation to a proposal and > the discussion that happened on it. > > We currently do not have a consistent overview of all proposals, the > activity on those and their status. > > Technically speaking, proposals could fit pretty well into the GitHub > pull-request workflow and, once accepted, serve as a reference, provide > insight into the agreed on ideas or even serve as documentation. > > What I am thinking of is a space on the web site that: > * lists the current proposals built from a query against open PRs with e.g. > the 'proposal' label, > * lists of closed proposals, closed PRs (dropped ideas or approaches), > * list of accepted proposals, merged PRs > > Moving proposals to PRs containing markdown (or asciidoc), would close the > "media break" and fix nicely with "it happened on the mailing list." > > I'd like to not go into the technical details or where the proposals would > live in this discussion, but rather get your thoughts about the idea in > general. > Just so much: GitHub has a good edit functionality with a live markdown > preview as a split view [2]. > > Cheers, > Robert > > > [1] https://lists.apache.org/thread/dnvfck8owpz0z1n1f93mnjm2nlcjp3ym > [2] https://github.dev/apache/polaris/blob/main/README.md >
