Hi JB, all, Following up on this discussion, I put together a small PoC to make it easier for authors to keep using Google Docs while meeting the need to preserve proposal documents in the repository: https://github.com/apache/polaris/pull/5587
The idea is to make that archival step mostly automatic. An author adds a version label and a Google Doc link to one YAML manifest. The tool captures Markdown and images, then fills in the Google revision and snapshot paths. Authors can preview locally, or let CI in their fork generate and commit the result. Captured versions stay frozen while the live Doc can continue to evolve. This is only a PoC to try the workflow and gather feedback. The snapshot directory used here is for demonstration. For actual integration, snapshots would go in the existing repository location for the corresponding documentation. I used the Tag proposal as a working example and verified the CI commit flow. The PR includes setup instructions if anyone would like to try another document. The current importer requires “Anyone with the link and Editor access". Comments are not archived, so discussion summaries and decisions still need to come back to this list. Would this make the Google Docs workflow easier to use? Feedback on the setup and export quality would be especially helpful. -ej On Tue, Jun 2, 2026 at 6:03 AM Jean-Baptiste Onofré <[email protected]> wrote: > Hi, > > Thank you for the feedback; those are all valid points. I primarily > wanted to get a community update on this discussion. > > I don't believe we should force authors to use a specific format, > whether Google Docs or Markdown. However, we should ensure that > "completed" Google Doc proposals are exported and stored in our > repository. If a proposal is eventually integrated into the > documentation once the implementation is finished, I think that serves > as an effective two-step process. > > Regards, > JB > > On Mon, Jun 1, 2026 at 11: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$ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
