Hi EJ That looks very promising! Thanks EJ!
Let me take a look and get back to you. Regards JB On Wed, Sep 23, 2026 at 5:02 PM EJ Wang <[email protected]> wrote: > 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$ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
