Re: [DISCUSSION] Proposal docs as markdown

[Jean-Baptiste Onofré <jb...@nanthrax.net>]

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 <tr...@gmail.com> 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 <rm...@gmail.com>
> 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 <fl...@gmail.com> 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 <rmannibucau@gmail.com
> > >
> > > 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 <fl...@gmail.com> 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 <dimas@apache.org
> > >
> > > > > 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 <
> > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > 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é <
> > > > jb@nanthrax.net
> > > > > >
> > > > > > > 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
> > > > > > > > proposal@polaris.apache.org mailing list to regularly send the
> > > > > > proposal
> > > > > > > as
> > > > > > > > md (to archive).
> > > > > > > >
> > > > > > > > Regards
> > > > > > > > JB
> > > > > > > >
> > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <su...@apache.org>
> > > > 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 <
> > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > 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 <
> > > snazy@snazy.de
> > > > >
> > > > > > > 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é <
> > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > 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 <
> > > > > > flyrain000@gmail.com
> > > > > > > >
> > > > > > > > > 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
> > > <
> > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > >
> > > > > > > > > > > > > > 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 <
> > > > > > > snazy@snazy.de
> > > > > > > > >
> > > > > > > > > > > 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 dev@polaris.a.o
> > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >

Re: [DISCUSSION] Proposal docs as markdown

[Dmitri Bourlatchkov <di...@apache.org>]

Hi JB,

Thanks for reviving this thread.

I very much would like to give .md files another try. My old points in
favour of this approach (from previous emails) still stand in addition to
your new points regarding AI.

My experience as a reviewer with Anand's recent proposals expressed as .md
files was positive.

Cheers,
Dmitri.

On Mon, Jun 1, 2026 at 1:52 AM Jean-Baptiste Onofré <jb...@nanthrax.net> 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 <tr...@gmail.com>
> 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 <rmannibucau@gmail.com
> >
> > 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 <fl...@gmail.com> 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 <
> rmannibucau@gmail.com
> > > >
> > > > 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 <fl...@gmail.com> 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 <
> dimas@apache.org
> > > >
> > > > > > 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 <
> > > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > > 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é <
> > > > > jb@nanthrax.net
> > > > > > >
> > > > > > > > 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
> > > > > > > > > proposal@polaris.apache.org mailing list to regularly
> send the
> > > > > > > proposal
> > > > > > > > as
> > > > > > > > > md (to archive).
> > > > > > > > >
> > > > > > > > > Regards
> > > > > > > > > JB
> > > > > > > > >
> > > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <
> sungwy@apache.org>
> > > > > 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 <
> > > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > > 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 <
> > > > snazy@snazy.de
> > > > > >
> > > > > > > > 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é <
> > > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > > 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 <
> > > > > > > flyrain000@gmail.com
> > > > > > > > >
> > > > > > > > > > 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
> > > > <
> > > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > > >
> > > > > > > > > > > > > > > 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
> <
> > > > > > > > snazy@snazy.de
> > > > > > > > > >
> > > > > > > > > > > > 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
> dev@polaris.a.o
> > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
>

Re: [DISCUSSION] Proposal docs as markdown

[Adnan Hemani via dev <de...@polaris.apache.org>]

Hi JB,

Completely a +1 to all of Yufei's points here. AI tooling is definitely
improving for Google Docs (the OpenLineage proposal I sent earlier is
evidence of that - AI tooling was used in the drafting and revising of that
:). Instead of changing our processes to something with a definite limit
(GitHub's rendering of larger PRs is very slow and one could say unusuable
past a certain limit), I'd prefer that folks rather adjust their tooling to
the already-followed processes.

Best,
Adnan Hemani

On Mon, Jun 1, 2026 at 2:30 PM Yufei Gu <fl...@gmail.com> 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é <jb...@nanthrax.net>
> 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 <tr...@gmail.com>
> > 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 <
> rmannibucau@gmail.com
> > >
> > > 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 <fl...@gmail.com> 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 <
> > rmannibucau@gmail.com
> > > > >
> > > > > 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 <fl...@gmail.com> 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 <
> > dimas@apache.org
> > > > >
> > > > > > > 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 <
> > > > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > > > 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é <
> > > > > > jb@nanthrax.net
> > > > > > > >
> > > > > > > > > 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
> > > > > > > > > > proposal@polaris.apache.org mailing list to regularly
> > send the
> > > > > > > > proposal
> > > > > > > > > as
> > > > > > > > > > md (to archive).
> > > > > > > > > >
> > > > > > > > > > Regards
> > > > > > > > > > JB
> > > > > > > > > >
> > > > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <
> > sungwy@apache.org>
> > > > > > 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 <
> > > > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > > > 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 <
> > > > > snazy@snazy.de
> > > > > > >
> > > > > > > > > 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é <
> > > > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > > > 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 <
> > > > > > > > flyrain000@gmail.com
> > > > > > > > > >
> > > > > > > > > > > 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
> > > > > <
> > > > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > 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
> > <
> > > > > > > > > snazy@snazy.de
> > > > > > > > > > >
> > > > > > > > > > > > > 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
> > dev@polaris.a.o
> > > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> >
>

Re: [DISCUSSION] Proposal docs as markdown

[EJ Wang <ej...@gmail.com>]

Hi JB, Dmitri, all,

Thanks for taking a look! Following up on the feedback here and on the PoC
PR <https://github.com/apache/polaris/pull/5587>, I'd like to hear from
proposal authors who would find this useful.

This follows the direction discussed earlier in this thread: authors can
keep using Google Docs for collaboration, while preserving proposals in the
repository. The PoC is meant to make that archival step easier for people
with existing Google Docs proposals. Authors who prefer Markdown can keep
their current workflow.

I've tried it with the Tag proposal. Would anyone with another Google Docs
proposal be interested in trying the workflow? I'd be happy to help with
the first run. Feedback on the setup effort and whether the exported
Markdown and images are useful for review would help us decide whether to
take this further.

The PR currently includes both the tool and the Tag snapshot to demonstrate
the workflow end to end. As discussed on the PR, I'll split them into
separate PRs before merging.

-ej


On Wed, 23 Sep 2026 19:16:55 +0200, Jean-Baptiste Onofré <jb...@nanthrax.net>
wrote:

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 <
ej.wang.dev.interest@gmail.com> 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é <jb...@nanthrax.net> > 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 <
flyrain000@gmail.com> 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é <jb@nanthrax.net > > > > > 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 <tr...@gmail.com> > > > > 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 < > > rmannibucau@gmail.com > > > > > > > > > >
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 <fl...@gmail.com> 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 <
> > > > rmannibucau@gmail.com > > > > > > > > > > > > > > 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 <fl...@gmail.com> > 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 < > > > > dimas@apache.org
> > > > > > > > > > > > > > > > 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 < > > > > >
> > > > > dev@polaris.apache.org> 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 <fl...@gmail.com> > > >
> > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM > > > > > > > >
> > > To: dev@polaris.apache.org <de...@polaris.apache.org> > > > > > > > > >
> > 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é < > > > > > > > >
jb@nanthrax.net > > > > > > > > > > > > > > > > > > > > > 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 > > > > > > >
> > > > > proposal@polaris.apache.org mailing list to > regularly > > > >
send the > > > > > > > > > > proposal > > > > > > > > > > > as > > > > > >
> > > > > > md (to archive). > > > > > > > > > > > > > > > > > > > > > > >
> Regards > > > > > > > > > > > > JB > > > > > > > > > > > > > > > > > > >
> > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun < > > > >
sungwy@apache.org> > > > > > > > > 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 > < > > > > > > > > > > > > >
russell.spitzer@gmail.com> > > > > > > > > > > > > > > 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 < > > > > > > >
snazy@snazy.de > > > > > > > > > > > > > > > > > > > > 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é < > > > > > > > > > > > >
> jb@nanthrax.net> > > > > > > > > > > > > > > > > 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 < > > > > > > > > > > flyrain000@gmail.com > > > > > > > > > > > >
> > > > > > > > > > > > > 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 > > > > > > > < > > > > > > > > > > > > > > >
dimas@apache.org > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
> > > > > > 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 > > > >
< > > > > > > > > > > > snazy@snazy.de > > > > > > > > > > > > > > > > > >
> > > > > > > > > > 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 > > > >
dev@polaris.a.o > > > > > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > > > > > > >

Re: [DISCUSSION] Proposal docs as markdown

[Jean-Baptiste Onofré <jb...@nanthrax.net>]

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 <ej...@gmail.com>
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é <jb...@nanthrax.net>
> 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 <fl...@gmail.com> 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é <jb@nanthrax.net
> >
> > > 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 <tr...@gmail.com>
> > > > 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 <
> > rmannibucau@gmail.com
> > > > >
> > > > > 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 <fl...@gmail.com> 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 <
> > > > rmannibucau@gmail.com
> > > > > > >
> > > > > > > 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 <fl...@gmail.com>
> 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 <
> > > > dimas@apache.org
> > > > > > >
> > > > > > > > > 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 <
> > > > > > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > > > > > 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é <
> > > > > > > > jb@nanthrax.net
> > > > > > > > > >
> > > > > > > > > > > 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
> > > > > > > > > > > > proposal@polaris.apache.org mailing list to
> regularly
> > > > send the
> > > > > > > > > > proposal
> > > > > > > > > > > as
> > > > > > > > > > > > md (to archive).
> > > > > > > > > > > >
> > > > > > > > > > > > Regards
> > > > > > > > > > > > JB
> > > > > > > > > > > >
> > > > > > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <
> > > > sungwy@apache.org>
> > > > > > > > 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
> <
> > > > > > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > > > > > 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 <
> > > > > > > snazy@snazy.de
> > > > > > > > >
> > > > > > > > > > > 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é <
> > > > > > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > > > > > 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 <
> > > > > > > > > > flyrain000@gmail.com
> > > > > > > > > > > >
> > > > > > > > > > > > > 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
> > > > > > > <
> > > > > > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > 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
> > > > <
> > > > > > > > > > > snazy@snazy.de
> > > > > > > > > > > > >
> > > > > > > > > > > > > > > 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
> > > > dev@polaris.a.o
> > > > > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > >
> >
> >
>

Re: [DISCUSSION] Proposal docs as markdown

[Dmitri Bourlatchkov <di...@apache.org>]

Hi EJ,

Interesting tool! If other people find it helpful I think we can give it
a try.

Cheers,
Dmitri.

On Wed, Sep 23, 2026 at 11:02 AM EJ Wang <ej...@gmail.com>
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é <jb...@nanthrax.net>
> 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 <fl...@gmail.com> 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é <jb@nanthrax.net
> >
> > > 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 <tr...@gmail.com>
> > > > 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 <
> > rmannibucau@gmail.com
> > > > >
> > > > > 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 <fl...@gmail.com> 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 <
> > > > rmannibucau@gmail.com
> > > > > > >
> > > > > > > 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 <fl...@gmail.com>
> 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 <
> > > > dimas@apache.org
> > > > > > >
> > > > > > > > > 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 <
> > > > > > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > > > > > 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é <
> > > > > > > > jb@nanthrax.net
> > > > > > > > > >
> > > > > > > > > > > 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
> > > > > > > > > > > > proposal@polaris.apache.org mailing list to
> regularly
> > > > send the
> > > > > > > > > > proposal
> > > > > > > > > > > as
> > > > > > > > > > > > md (to archive).
> > > > > > > > > > > >
> > > > > > > > > > > > Regards
> > > > > > > > > > > > JB
> > > > > > > > > > > >
> > > > > > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <
> > > > sungwy@apache.org>
> > > > > > > > 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
> <
> > > > > > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > > > > > 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 <
> > > > > > > snazy@snazy.de
> > > > > > > > >
> > > > > > > > > > > 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é <
> > > > > > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > > > > > 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 <
> > > > > > > > > > flyrain000@gmail.com
> > > > > > > > > > > >
> > > > > > > > > > > > > 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
> > > > > > > <
> > > > > > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > 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
> > > > <
> > > > > > > > > > > snazy@snazy.de
> > > > > > > > > > > > >
> > > > > > > > > > > > > > > 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
> > > > dev@polaris.a.o
> > > > > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > >
> >
> >
>

Re: [DISCUSSION] Proposal docs as markdown

[EJ Wang <ej...@gmail.com>]

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é <jb...@nanthrax.net> 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 <fl...@gmail.com> 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é <jb...@nanthrax.net>
> > 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 <tr...@gmail.com>
> > > 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 <
> rmannibucau@gmail.com
> > > >
> > > > 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 <fl...@gmail.com> 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 <
> > > rmannibucau@gmail.com
> > > > > >
> > > > > > 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 <fl...@gmail.com> 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 <
> > > dimas@apache.org
> > > > > >
> > > > > > > > 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 <
> > > > > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > > > > 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é <
> > > > > > > jb@nanthrax.net
> > > > > > > > >
> > > > > > > > > > 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
> > > > > > > > > > > proposal@polaris.apache.org mailing list to regularly
> > > send the
> > > > > > > > > proposal
> > > > > > > > > > as
> > > > > > > > > > > md (to archive).
> > > > > > > > > > >
> > > > > > > > > > > Regards
> > > > > > > > > > > JB
> > > > > > > > > > >
> > > > > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <
> > > sungwy@apache.org>
> > > > > > > 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 <
> > > > > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > > > > 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 <
> > > > > > snazy@snazy.de
> > > > > > > >
> > > > > > > > > > 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é <
> > > > > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > > > > 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 <
> > > > > > > > > flyrain000@gmail.com
> > > > > > > > > > >
> > > > > > > > > > > > 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
> > > > > > <
> > > > > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > 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
> > > <
> > > > > > > > > > snazy@snazy.de
> > > > > > > > > > > >
> > > > > > > > > > > > > > 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
> > > dev@polaris.a.o
> > > > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > >
>
>

Re: [DISCUSSION] Proposal docs as markdown

[Jean-Baptiste Onofré <jb...@nanthrax.net>]

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 <fl...@gmail.com> 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é <jb...@nanthrax.net>
> 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 <tr...@gmail.com>
> > 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 <rmannibucau@gmail.com
> > >
> > > 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 <fl...@gmail.com> 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 <
> > rmannibucau@gmail.com
> > > > >
> > > > > 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 <fl...@gmail.com> 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 <
> > dimas@apache.org
> > > > >
> > > > > > > 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 <
> > > > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > > > 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é <
> > > > > > jb@nanthrax.net
> > > > > > > >
> > > > > > > > > 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
> > > > > > > > > > proposal@polaris.apache.org mailing list to regularly
> > send the
> > > > > > > > proposal
> > > > > > > > > as
> > > > > > > > > > md (to archive).
> > > > > > > > > >
> > > > > > > > > > Regards
> > > > > > > > > > JB
> > > > > > > > > >
> > > > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <
> > sungwy@apache.org>
> > > > > > 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 <
> > > > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > > > 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 <
> > > > > snazy@snazy.de
> > > > > > >
> > > > > > > > > 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é <
> > > > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > > > 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 <
> > > > > > > > flyrain000@gmail.com
> > > > > > > > > >
> > > > > > > > > > > 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
> > > > > <
> > > > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > 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
> > <
> > > > > > > > > snazy@snazy.de
> > > > > > > > > > >
> > > > > > > > > > > > > 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
> > dev@polaris.a.o
> > > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> >

Re: [DISCUSSION] Proposal docs as markdown

[Yufei Gu <fl...@gmail.com>]

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é <jb...@nanthrax.net>
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 <tr...@gmail.com>
> 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 <rmannibucau@gmail.com
> >
> > 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 <fl...@gmail.com> 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 <
> rmannibucau@gmail.com
> > > >
> > > > 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 <fl...@gmail.com> 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 <
> dimas@apache.org
> > > >
> > > > > > 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 <
> > > > > > > dev@polaris.apache.org> 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 <fl...@gmail.com>
> > > > > > > > Date: Friday, February 20, 2026 at 11:12 AM
> > > > > > > > To: dev@polaris.apache.org <de...@polaris.apache.org>
> > > > > > > > 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é <
> > > > > jb@nanthrax.net
> > > > > > >
> > > > > > > > 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
> > > > > > > > > proposal@polaris.apache.org mailing list to regularly
> send the
> > > > > > > proposal
> > > > > > > > as
> > > > > > > > > md (to archive).
> > > > > > > > >
> > > > > > > > > Regards
> > > > > > > > > JB
> > > > > > > > >
> > > > > > > > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <
> sungwy@apache.org>
> > > > > 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 <
> > > > > > > > > > russell.spitzer@gmail.com>
> > > > > > > > > > > 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 <
> > > > snazy@snazy.de
> > > > > >
> > > > > > > > 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é <
> > > > > > > > > > jb@nanthrax.net>
> > > > > > > > > > > > > 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 <
> > > > > > > flyrain000@gmail.com
> > > > > > > > >
> > > > > > > > > > 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
> > > > <
> > > > > > > > > > > > dimas@apache.org
> > > > > > > > > > > > > >
> > > > > > > > > > > > > > > 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
> <
> > > > > > > > snazy@snazy.de
> > > > > > > > > >
> > > > > > > > > > > > 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
> dev@polaris.a.o
> > > > > > > > > > > > > > > > > - 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$
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
>