Hi JB, Completely a +1 to all of Yufei's points here. AI tooling is definitely improving for Google Docs (the OpenLineage proposal I sent earlier is evidence of that - AI tooling was used in the drafting and revising of that :). Instead of changing our processes to something with a definite limit (GitHub's rendering of larger PRs is very slow and one could say unusuable past a certain limit), I'd prefer that folks rather adjust their tooling to the already-followed processes.
Best, Adnan Hemani On Mon, Jun 1, 2026 at 2:30 PM Yufei Gu <[email protected]> wrote: > Hi JB, > > I still think Google Docs is essentially a better option than Markdown > proposals at this point. It's instantly readable for any reviewer while > modification happens, it is easier to read and draw diagrams. One practical > issue is that GitHub PR pages become extremely slow when a proposal > attracts a relatively small number of comments, like 80 - 100 comments. > Following and reviewing a design discussion can become quite inefficient > for both authors and reviewers. In my experience, Google Docs provides a > smoother experience for collaborative design discussions, especially during > the early exploration and iteration phases. > > AI tooling is certainly a point in favor of Markdown. However, AI tools > already work reasonably well with Google Docs, and that support continues > to improve rapidly, so I don't see that as a decisive factor today. > > That said, I'm completely fine with piloting the Markdown proposal approach > and gathering some real world experience. I would just prefer that we keep > Google Docs as a valid option rather than making Markdown the only > supported path. > > Yufei > > > On Sun, May 31, 2026 at 10:52 PM Jean-Baptiste Onofré <[email protected]> > wrote: > > > Hi everyone, > > > > Given the recent advancements in AI tools, I believe this thread > > deserves an update. To experiment with the process we discussed, I am > > currently working on the Polaris Directory proposal/PR, which includes > > a proposal/documentation in Markdown format. > > > > As a reminder, our discussion centers on the potential transition to > > using Markdown and PRs for proposals to better align with ASF > > infrastructure. > > > > What are your thoughts on this approach? Still a preference for Google > Doc? > > > > Regards, > > JB > > > > On Thu, Mar 5, 2026 at 3:34 AM Travis Bowen <[email protected]> > > wrote: > > > > > > I’d also find the strict requirement for markdown and PRs to be a > larger > > > burden vs Google Docs as a reviewer or contributor for many of the same > > > reasons expressed, but also realize as Romain says that this is > probably > > > something you won’t be able to get complete agreement on in a larger > > > community. > > > > > > I’d +1 to JBs proposal - I like that it takes a step back and sees if > we > > > can start with some incremental process improvements while allowing for > > > further discussions about the ideal state. > > > > > > -Travis > > > > > > On Wed, Mar 4, 2026 at 3:47 PM Romain Manni-Bucau < > [email protected] > > > > > > wrote: > > > > > > > Well PR vs google docs is a habit thing, you get both camps and this > > is not > > > > really something you can get an agreement on from my past experience. > > > > That said what is true is that if you say "we did discuss it" and it > > was in > > > > the google doc, it never happent for apache - and it is good cause we > > don't > > > > archive google, it is not an official channel etc... > > > > So at some point - if keeping track of the decision process which was > > one > > > > concern - it must hit the list somehow. > > > > PR are a good compromise to have that for free and inline comment but > > > > without preview until you do use a chrome extension or the web > > rendering > > > > hack I spoke about, there is not yet any free lunch I guess. > > > > > > > > Side note: if you don't care about the history and decisions in the > > work > > > > document, gdoc is ok and you fall back on the "habit"/personal > > preference > > > > side of things if not obvious. > > > > > > > > Romain Manni-Bucau > > > > @rmannibucau <https://x.com/rmannibucau> | .NET Blog > > > > <https://dotnetbirdie.github.io/> | Blog < > > https://rmannibucau.github.io/> > > > > | Old > > > > Blog <http://rmannibucau.wordpress.com> | Github > > > > <https://github.com/rmannibucau> | LinkedIn > > > > <https://www.linkedin.com/in/rmannibucau> | Book > > > > < > > > > > > > https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064 > > > > > > > > > Javaccino founder (Java/.NET service - contact via linkedin) > > > > > > > > > > > > Le jeu. 5 mars 2026 à 00:16, Yufei Gu <[email protected]> a > écrit : > > > > > > > > > Google doc + dev mailing discussion is the way for many ASF > > projects. I > > > > > personally didn't see a major issue with that. You can always > > summarize > > > > the > > > > > design doc or PR status in the dev mailing thread, concluding with > > the > > > > > consensus or any related outcomes. I'm not sure if we need to put > > every > > > > > single details in the dev mailing list, that's not practical and > > using PR > > > > > for it has exactly the same issue. > > > > > > > > > > Yufei > > > > > > > > > > > > > > > On Wed, Mar 4, 2026 at 2:39 PM Romain Manni-Bucau < > > [email protected] > > > > > > > > > > wrote: > > > > > > > > > > > Hi guys, > > > > > > > > > > > > Hmm, your last comment kind of kills google docs for Apache > Polaris > > > > > Yufei - > > > > > > even if I understand the intent. > > > > > > There if it is nowhere on the list it is not so until you make > > comments > > > > > > forwarded to the dev list as PR ones the solution doesn't work > > well for > > > > > > apache projects IMHO. > > > > > > > > > > > > Did you think about providing a light UI (pure frontend, just > > using the > > > > > > browser github auth to fetch the doc and render it in the > browser) > > on > > > > the > > > > > > polaris website able to do the rendering directly even on PR? can > > make > > > > > kind > > > > > > of the best of both worlds, will just need to switch between two > > tabs > > > > to > > > > > > comment but it is kind of already the case anyway no? > > > > > > > > > > > > Alternative would be to ensure discussions happen on the list, I > > know > > > > > some > > > > > > projects copy/paste the full proposal in a mail instead of > > dropping a > > > > > > google doc link but it sill miss the discussion :(. > > > > > > > > > > > > Romain Manni-Bucau > > > > > > @rmannibucau <https://x.com/rmannibucau> | .NET Blog > > > > > > <https://dotnetbirdie.github.io/> | Blog < > > > > https://rmannibucau.github.io/ > > > > > > > > > > > > | Old > > > > > > Blog <http://rmannibucau.wordpress.com> | Github > > > > > > <https://github.com/rmannibucau> | LinkedIn > > > > > > <https://www.linkedin.com/in/rmannibucau> | Book > > > > > > < > > > > > > > > > > > > > > > > > > https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064 > > > > > > > > > > > > > Javaccino founder (Java/.NET service - contact via linkedin) > > > > > > > > > > > > > > > > > > Le mer. 4 mars 2026 à 23:12, Yufei Gu <[email protected]> a > > écrit : > > > > > > > > > > > > > I agree with Adnan and JB that using PRs for design proposals > > makes > > > > it > > > > > > > harder for the broader audience who mainly review the document > > and > > > > > follow > > > > > > > the discussion. > > > > > > > > > > > > > > When a PR is updated, earlier comments often become outdated > and > > > > > collapse > > > > > > > automatically. This makes it difficult for readers to follow > the > > full > > > > > > > discussion and understand how the design evolved. In contrast, > > Google > > > > > > Docs > > > > > > > keeps comment threads visible and easier to navigate, which > helps > > > > > > reviewers > > > > > > > track feedback and respond in context. I have seen a lot of > good > > > > > > discussion > > > > > > > in the comment thread. Diagrams are another practical aspect. > > Design > > > > > > > proposals often iterate on diagrams, and updating them is much > > easier > > > > > in > > > > > > > Google Docs, while PR workflows usually require external tools > > and > > > > > > > additional commits. Overall, Google Docs tends to be more > > reviewer > > > > > > friendly > > > > > > > for early design exploration and faster iteration. > > > > > > > > > > > > > > I'd follow JB’s suggestion to take a step back for now. > > > > > > > > > > > > > > Yufei > > > > > > > > > > > > > > > > > > > > > On Wed, Mar 4, 2026 at 1:46 PM Dmitri Bourlatchkov < > > [email protected] > > > > > > > > > > > > wrote: > > > > > > > > > > > > > > > From Anand: > > > > > > > > > > > > > > > > > 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. > > > > > > > > > > > > > > > > I second that assessment. > > > > > > > > > > > > > > > > Cheers, > > > > > > > > Dmitri. > > > > > > > > > > > > > > > > On Wed, Mar 4, 2026 at 2:09 PM 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$ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
