Respectfully, I disagree in my experience both as a proposal writer and reviewer. As a reviewer especially, it is much easier to read and interact with a proposal in a document format than an un-rendered markdown file as a GitHub diff. Add the fact that some proposals may require diagrams or visualizations of concepts, and markdowns quickly become very hard to work with while a proposal is in development and review.
I can still see some benefit to using a markdown to "preserve" an approved proposal. While reviewing a proposal, I still lean significantly toward Google Docs or a similar service. Best, Adnan Hemani On Wed, Mar 4, 2026 at 11:09 AM Anand Kumar Sankaran via dev < [email protected]> wrote: > Based on Dmitri’s suggestion, I tried a PR + markdown for > https://github.com/apache/polaris/pull/3924. > > This is the third proposal I have written (two as Google Docs). I find the > cognitive burden of trying to deal with comments and iterating is lower as > a PR - dealing with comments in Google Docs is harder. > > - > Anand > > From: Yufei Gu <[email protected]> > Date: Friday, February 20, 2026 at 11:12 AM > To: [email protected] <[email protected]> > Subject: Re: [DISCUSSION] Proposal docs as markdown > > This Message Is From an External Sender > This message came from outside your organization. > Report Suspicious< > https://us-phishalarm-ewt.proofpoint.com/EWT/v1/Iz9xO38YGHZK!YhNDZABkHi1B6hTBHcVu8kQI_AzqHuMLYK3YJ2WcpkFtXQrgqDnGO46G3WQrLGeP4jCYxsQABEKuLtkm2Dgju1lOYXIr6svqDiAZmLXEUbE6zADH9FL9vxAlIuqYPVDq$ > > > > > > One slightly orthogonal thought: proposals committed as markdown in the > git repo are also much easier for tooling and automation (including > AI-based tools) to reason about than external Docs… That may or may not > matter today, but it’s probably worth keeping in mind. > > That is a good point. My main concern is that many design docs and > proposals become outdated once implementation begins. When that happens, > the document can become misleading. That creates confusion not only for > humans, but also for any tooling or AI systems that rely on those > documents as a source of truth. > > If we move toward using Markdown in the repo, we should consider how to > keep the document aligned with the implementation over time, or be very > explicit about when a proposal is considered historical context rather than > current design. I didn't see many people doing that, TBH. > > Yufei > > > On Thu, Feb 19, 2026 at 10:10 PM Jean-Baptiste Onofré <[email protected]> > wrote: > > > Hi > > > > I think we all agree that Google Docs works well for collaboration on > > proposals. I don't think we should change it. > > The point is how we are "storing" these proposals in the ASF infra as > some > > points (for instance, the GH PR reviews and GH Issues are stored in the > ASF > > infra thanks to the notification schema > > > https://urldefense.com/v3/__https://github.com/apache/polaris/blob/main/.asf.yaml*L80__;Iw!!Iz9xO38YGHZK!89RRPA_7GgBy9xjmDl9fqFt_2hDlH0RfXNGgyvoMAhdUAgADi08ZUPy4MJVSuIW095SBIwcCZ1eVp5owZ9F2WDY$, > the lists are > > archived and can be used to recreate the resources if needed). > > > > I don't think we need to over engineer or overcomplicate the process > here. > > The purpose is really to have backup on the Google Doc proposals. > > > > Maybe we should just keep using Google Docs for now, and regularly export > > the Google Doc as markdown (it's possible in File -> Download -> Markdown > > (md)) to populate a folder on the repo (as backup). > > I'm sure we can do that via a process/API call too. Also, we can create a > > [email protected] mailing list to regularly send the proposal > as > > md (to archive). > > > > Regards > > JB > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <[email protected]> wrote: > > > > > Hi all, this is a good discussion. Thanks Robert and Mika for raising > > this. > > > > > > I do think Google Docs work really well for drafting RFCs and > discussing > > > ideas early on. The low friction for collaboration, comments, and > > diagrams > > > makes it much easier to shape a proposal before there’s any real > > consensus. > > > The most important invariant, in my view, is that we abide by the “if > it > > > didn’t happen on the mailing list, it didn’t happen” ASF rule[1], > which I > > > believe most proposals already follow. > > > > > > Dmitri - conceptually, the freezing and archiving approach does sound > > > great. Where I think more clarity would help, before we adopt it, is > > around > > > the details of the process. Defining and publishing guidelines on when > a > > > proposal is considered “accepted” and ready to be finalized, who makes > > that > > > call, and whether we expect a version committed to git to stay in sync > if > > > the implementation evolves I think would be good to answer up front. > > > Defining that process would also help us evaluate whether the process > > will > > > remain lightweight or risk adding unnecessary overhead. > > > > > > One slightly orthogonal thought: proposals committed as markdown in the > > > git repo are also much easier for tooling and automation (including > > > AI-based tools) to reason about than external Docs… That may or may not > > > matter today, but it’s probably worth keeping in mind. > > > > > > Cheers, > > > Sung > > > > > > [1] > > > > > > https://urldefense.com/v3/__https://community.apache.org/contributors/mailing-lists.html*inclusion-and-transparency__;Iw!!Iz9xO38YGHZK!89RRPA_7GgBy9xjmDl9fqFt_2hDlH0RfXNGgyvoMAhdUAgADi08ZUPy4MJVSuIW095SBIwcCZ1eVp5ow0BwAr1o$ > > > > > > > > > On 2026/02/20 00:39:44 Dmitri Bourlatchkov wrote: > > > > Hi All, > > > > > > > > Russell made a good point that proposal docs basically stop evolving > as > > > > soon some code for that proposal is committed. > > > > > > > > However, I think old proposal texts still have value in the > historical > > > > context, especially if we link them to implementation PRs. > > > > > > > > Process-wise, in my personal experience, cross-referencing gDocs and > > code > > > > is very hard. > > > > > > > > So, I would like to propose explicitly "freezing" gDoc proposals > before > > > > implementing them. Maybe we could convert them to PDF and commit to > the > > > > docs section in the source repo. WDYT? > > > > > > > > Markdown proposals are already frozen once committed to git. > > > > > > > > Cheers, > > > > Dmitri. > > > > > > > > On Thu, Feb 19, 2026 at 11:25 AM Russell Spitzer < > > > [email protected]> > > > > wrote: > > > > > > > > > I have no problem with leaving a final copy in markdown, but I > > > definitely > > > > > think Google docs are a lower friction method > > > > > of doing proposals. I do feel like most folks do not keep design > > > documents > > > > > in sync with actual implementations and I > > > > > am not sure having them go through a PR process would make that > > easier. > > > > > > > > > > In general I think this is a "don't fix what isn't broke" > situation, > > > the > > > > > current setup is good enough and familiar to users of a > > > > > lot of other ASF projects. If folks can choose between docs and PR > > for > > > > > proposals I think that's all fine, and I think it's probably > > > > > a good idea to have final proposals inside the repo but I wouldn't > > > consider > > > > > it critical. > > > > > > > > > > I know Docs are outside ASF, but our whole PR review process is > > *also* > > > > > outside ASF :) > > > > > > > > > > On Thu, Feb 19, 2026 at 8:47 AM Robert Stupp <[email protected]> > wrote: > > > > > > > > > > > I think it's worth a try. > > > > > > > > > > > > I took a stab at listing the proposals on the Polaris website; PR > > > [3835] > > > > > is > > > > > > up. > > > > > > > > > > > > Robert > > > > > > > > > > > > [3835] > https://urldefense.com/v3/__https://github.com/apache/polaris/pull/3835__;!!Iz9xO38YGHZK!89RRPA_7GgBy9xjmDl9fqFt_2hDlH0RfXNGgyvoMAhdUAgADi08ZUPy4MJVSuIW095SBIwcCZ1eVp5ow3Tg7y1w$ > > > > > > > > > > > > On Thu, Feb 19, 2026 at 7:57 AM Jean-Baptiste Onofré < > > > [email protected]> > > > > > > wrote: > > > > > > > > > > > > > Hi Yufei, > > > > > > > > > > > > > > I agree with your points and appreciate the collaborative, > > > > > user-friendly > > > > > > > nature of Google Docs. > > > > > > > > > > > > > > We can certainly continue using Google Docs during the drafting > > and > > > > > > > preparation phases. However, since Google Docs exists outside > of > > > the > > > > > ASF > > > > > > > infrastructure, we should ensure the final versions of > proposals > > > are > > > > > > > exported to and stored in our repository. This ensures they are > > > > > properly > > > > > > > archived within the ASF-managed source system (remember that > > > GitHub is > > > > > a > > > > > > > mirror of GitBox which is ASF managed source repository). > > > > > > > > > > > > > > I suggest we remain flexible to encourage as many contributions > > as > > > > > > > possible: > > > > > > > > > > > > > > 1. If a contributor prefers Google Docs for drafting and > review, > > > that > > > > > > works > > > > > > > well. The document can then be exported to the website once it > > > reaches > > > > > a > > > > > > > "final" stage. > > > > > > > 2. If a contributor prefers to submit a proposal via a Pull > > > Request in > > > > > > > Markdown, that is also acceptable. > > > > > > > > > > > > > > If there are no objections, I would like to experiment with the > > > > > Markdown > > > > > > > approach for the Delegation Services proposal. > > > > > > > > > > > > > > What do you think? > > > > > > > > > > > > > > Regards, > > > > > > > JB > > > > > > > > > > > > > > > > > > > > > On Tue, Feb 17, 2026 at 7:55 PM Yufei Gu <[email protected] > > > > > wrote: > > > > > > > > > > > > > > > Hi all, > > > > > > > > > > > > > > > > In my experience, Google Docs works very well for design > > > discussions. > > > > > > The > > > > > > > > real time collaboration, quick iteration, and low barrier to > > > editing > > > > > > make > > > > > > > > it much easier to shape ideas, especially in the early > stages. > > > > > Multiple > > > > > > > > people can work on a single Google Doc seamlessly, whereas > > > > > coordinating > > > > > > > > edits across one PR with several contributors is not as > > > > > > straightforward. > > > > > > > > Diagrams are often an important part of proposal discussions. > > > Adding, > > > > > > > > editing, and iterating on diagrams is much easier in Google > > > Docs. In > > > > > a > > > > > > PR > > > > > > > > workflow, updating diagrams usually requires external tools, > > and > > > new > > > > > > > > commits, which slows down iteration. > > > > > > > > > > > > > > > > The PR review process also works differently from open design > > > > > > > exploration. > > > > > > > > Long discussions can quickly accumulate dozens of comments, > > > making > > > > > the > > > > > > > page > > > > > > > > slower and harder to navigate. You've probably experienced > slow > > > > > GitHub > > > > > > PR > > > > > > > > pages when there are 80+ comments. And we would likely need > > > > > additional > > > > > > > > rules around approvals or change requests for proposal docs, > > > which > > > > > adds > > > > > > > > more process overhead. > > > > > > > > > > > > > > > > I believe Google Docs should remain a valid and practical > > option > > > for > > > > > > > > drafting and collaborative design discussions. I'd love to > > still > > > keep > > > > > > > that > > > > > > > > option. > > > > > > > > > > > > > > > > Yufei > > > > > > > > > > > > > > > > > > > > > > > > On Tue, Feb 17, 2026 at 10:26 AM Dmitri Bourlatchkov < > > > > > [email protected] > > > > > > > > > > > > > > > wrote: > > > > > > > > > > > > > > > > > Hi Robert, > > > > > > > > > > > > > > > > > > Excellent idea about leveraging the PR review process for > > > proposal > > > > > > > docs! > > > > > > > > > > > > > > > > > > I'm not sure we need to spend extra effort to publish > > > proposals on > > > > > > the > > > > > > > > main > > > > > > > > > site (unless it is easy :) ) as long as the contribution > > guide > > > is > > > > > > clear > > > > > > > > > about how to find them in GH. > > > > > > > > > > > > > > > > > > Once a proposal is implemented, the docs will naturally be > > > updated > > > > > > with > > > > > > > > > corresponding user-facing instructions. > > > > > > > > > > > > > > > > > > Cheers, > > > > > > > > > Dmitri. > > > > > > > > > > > > > > > > > > On Sun, Feb 15, 2026 at 8:41 AM Robert Stupp < > [email protected] > > > > > > > > wrote: > > > > > > > > > > > > > > > > > > > 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://urldefense.com/v3/__https://lists.apache.org/thread/dnvfck8owpz0z1n1f93mnjm2nlcjp3ym__;!!Iz9xO38YGHZK!89RRPA_7GgBy9xjmDl9fqFt_2hDlH0RfXNGgyvoMAhdUAgADi08ZUPy4MJVSuIW095SBIwcCZ1eVp5owMqc4FVQ$ > > > > > > > > > > [2] > https://urldefense.com/v3/__https://github.dev/apache/polaris/blob/main/README.md__;!!Iz9xO38YGHZK!89RRPA_7GgBy9xjmDl9fqFt_2hDlH0RfXNGgyvoMAhdUAgADi08ZUPy4MJVSuIW095SBIwcCZ1eVp5owAnBZVqU$ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
