That's valuable feedback, and I share those concerns. While writing in Markdown and the website integration are convenient, I find that the review process and discussions via comments are more difficult. This is something I have observed in other projects, such as ActiveMQ.
I suggest we take a step back. The starting point of this discussion was that Google Documents are "outside" the ASF "scope". Therefore, the primary goal is to find a way to store these documents within our own infrastructure and repository. To avoid overcomplicating the process, we could start with a simpler approach: 1. Create a GitHub Issue with the "proposal" label that includes a link to the Google Document (which is our current intended practice). 2. Once consensus is reached, close the GitHub issue. At this point, the Google Document can be exported as Markdown and added to the website. This allows us to continue using Google Documents for their collaborative features while ensuring the final version is preserved on our infrastructure. What do you think? Regards, JB On Wed, Mar 4, 2026 at 2:36 PM Adnan Hemani via dev <[email protected]> wrote: > 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$ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
