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$ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
