+1 to JB's proposal. I'm still not 100% sold on point 2 (exporting the Google Doc to markdown and adding it to the Polaris website) - but have no major reservations towards doing this if others think it is reasonable.
My only minor concern is maintenance of these proposals over time may become weak and/or non-existent (I've seen this happen in other Apache projects as well). But this is a bridge to cross if we get there. Best, Adnan Hemani On Wed, Mar 4, 2026 at 11:51 AM Jean-Baptiste Onofré <[email protected]> wrote: > 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$ >> > > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > >> > > >> > >> > >> >
