> One slightly orthogonal thought: proposals committed as markdown in the git repo are also much easier for tooling and automation (including AI-based tools) to reason about than external Docs… That may or may not matter today, but it’s probably worth keeping in mind.
That is a good point. My main concern is that many design docs and proposals become outdated once implementation begins. When that happens, the document can become misleading. That creates confusion not only for humans, but also for any tooling or AI systems that rely on those documents as a source of truth. If we move toward using Markdown in the repo, we should consider how to keep the document aligned with the implementation over time, or be very explicit about when a proposal is considered historical context rather than current design. I didn't see many people doing that, TBH. Yufei On Thu, Feb 19, 2026 at 10:10 PM Jean-Baptiste Onofré <[email protected]> wrote: > Hi > > I think we all agree that Google Docs works well for collaboration on > proposals. I don't think we should change it. > The point is how we are "storing" these proposals in the ASF infra as some > points (for instance, the GH PR reviews and GH Issues are stored in the ASF > infra thanks to the notification schema > https://github.com/apache/polaris/blob/main/.asf.yaml#L80, the lists are > archived and can be used to recreate the resources if needed). > > I don't think we need to over engineer or overcomplicate the process here. > The purpose is really to have backup on the Google Doc proposals. > > Maybe we should just keep using Google Docs for now, and regularly export > the Google Doc as markdown (it's possible in File -> Download -> Markdown > (md)) to populate a folder on the repo (as backup). > I'm sure we can do that via a process/API call too. Also, we can create a > [email protected] mailing list to regularly send the proposal as > md (to archive). > > Regards > JB > > On Fri, Feb 20, 2026 at 2:49 AM Sung Yun <[email protected]> wrote: > > > Hi all, this is a good discussion. Thanks Robert and Mika for raising > this. > > > > I do think Google Docs work really well for drafting RFCs and discussing > > ideas early on. The low friction for collaboration, comments, and > diagrams > > makes it much easier to shape a proposal before there’s any real > consensus. > > The most important invariant, in my view, is that we abide by the “if it > > didn’t happen on the mailing list, it didn’t happen” ASF rule[1], which I > > believe most proposals already follow. > > > > Dmitri - conceptually, the freezing and archiving approach does sound > > great. Where I think more clarity would help, before we adopt it, is > around > > the details of the process. Defining and publishing guidelines on when a > > proposal is considered “accepted” and ready to be finalized, who makes > that > > call, and whether we expect a version committed to git to stay in sync if > > the implementation evolves I think would be good to answer up front. > > Defining that process would also help us evaluate whether the process > will > > remain lightweight or risk adding unnecessary overhead. > > > > One slightly orthogonal thought: proposals committed as markdown in the > > git repo are also much easier for tooling and automation (including > > AI-based tools) to reason about than external Docs… That may or may not > > matter today, but it’s probably worth keeping in mind. > > > > Cheers, > > Sung > > > > [1] > > > https://community.apache.org/contributors/mailing-lists.html#inclusion-and-transparency > > > > > > On 2026/02/20 00:39:44 Dmitri Bourlatchkov wrote: > > > Hi All, > > > > > > Russell made a good point that proposal docs basically stop evolving as > > > soon some code for that proposal is committed. > > > > > > However, I think old proposal texts still have value in the historical > > > context, especially if we link them to implementation PRs. > > > > > > Process-wise, in my personal experience, cross-referencing gDocs and > code > > > is very hard. > > > > > > So, I would like to propose explicitly "freezing" gDoc proposals before > > > implementing them. Maybe we could convert them to PDF and commit to the > > > docs section in the source repo. WDYT? > > > > > > Markdown proposals are already frozen once committed to git. > > > > > > Cheers, > > > Dmitri. > > > > > > On Thu, Feb 19, 2026 at 11:25 AM Russell Spitzer < > > [email protected]> > > > wrote: > > > > > > > I have no problem with leaving a final copy in markdown, but I > > definitely > > > > think Google docs are a lower friction method > > > > of doing proposals. I do feel like most folks do not keep design > > documents > > > > in sync with actual implementations and I > > > > am not sure having them go through a PR process would make that > easier. > > > > > > > > In general I think this is a "don't fix what isn't broke" situation, > > the > > > > current setup is good enough and familiar to users of a > > > > lot of other ASF projects. If folks can choose between docs and PR > for > > > > proposals I think that's all fine, and I think it's probably > > > > a good idea to have final proposals inside the repo but I wouldn't > > consider > > > > it critical. > > > > > > > > I know Docs are outside ASF, but our whole PR review process is > *also* > > > > outside ASF :) > > > > > > > > On Thu, Feb 19, 2026 at 8:47 AM Robert Stupp <[email protected]> wrote: > > > > > > > > > I think it's worth a try. > > > > > > > > > > I took a stab at listing the proposals on the Polaris website; PR > > [3835] > > > > is > > > > > up. > > > > > > > > > > Robert > > > > > > > > > > [3835] https://github.com/apache/polaris/pull/3835 > > > > > > > > > > On Thu, Feb 19, 2026 at 7:57 AM Jean-Baptiste Onofré < > > [email protected]> > > > > > wrote: > > > > > > > > > > > Hi Yufei, > > > > > > > > > > > > I agree with your points and appreciate the collaborative, > > > > user-friendly > > > > > > nature of Google Docs. > > > > > > > > > > > > We can certainly continue using Google Docs during the drafting > and > > > > > > preparation phases. However, since Google Docs exists outside of > > the > > > > ASF > > > > > > infrastructure, we should ensure the final versions of proposals > > are > > > > > > exported to and stored in our repository. This ensures they are > > > > properly > > > > > > archived within the ASF-managed source system (remember that > > GitHub is > > > > a > > > > > > mirror of GitBox which is ASF managed source repository). > > > > > > > > > > > > I suggest we remain flexible to encourage as many contributions > as > > > > > > possible: > > > > > > > > > > > > 1. If a contributor prefers Google Docs for drafting and review, > > that > > > > > works > > > > > > well. The document can then be exported to the website once it > > reaches > > > > a > > > > > > "final" stage. > > > > > > 2. If a contributor prefers to submit a proposal via a Pull > > Request in > > > > > > Markdown, that is also acceptable. > > > > > > > > > > > > If there are no objections, I would like to experiment with the > > > > Markdown > > > > > > approach for the Delegation Services proposal. > > > > > > > > > > > > What do you think? > > > > > > > > > > > > Regards, > > > > > > JB > > > > > > > > > > > > > > > > > > On Tue, Feb 17, 2026 at 7:55 PM Yufei Gu <[email protected]> > > wrote: > > > > > > > > > > > > > Hi all, > > > > > > > > > > > > > > In my experience, Google Docs works very well for design > > discussions. > > > > > The > > > > > > > real time collaboration, quick iteration, and low barrier to > > editing > > > > > make > > > > > > > it much easier to shape ideas, especially in the early stages. > > > > Multiple > > > > > > > people can work on a single Google Doc seamlessly, whereas > > > > coordinating > > > > > > > edits across one PR with several contributors is not as > > > > > straightforward. > > > > > > > Diagrams are often an important part of proposal discussions. > > Adding, > > > > > > > editing, and iterating on diagrams is much easier in Google > > Docs. In > > > > a > > > > > PR > > > > > > > workflow, updating diagrams usually requires external tools, > and > > new > > > > > > > commits, which slows down iteration. > > > > > > > > > > > > > > The PR review process also works differently from open design > > > > > > exploration. > > > > > > > Long discussions can quickly accumulate dozens of comments, > > making > > > > the > > > > > > page > > > > > > > slower and harder to navigate. You've probably experienced slow > > > > GitHub > > > > > PR > > > > > > > pages when there are 80+ comments. And we would likely need > > > > additional > > > > > > > rules around approvals or change requests for proposal docs, > > which > > > > adds > > > > > > > more process overhead. > > > > > > > > > > > > > > I believe Google Docs should remain a valid and practical > option > > for > > > > > > > drafting and collaborative design discussions. I'd love to > still > > keep > > > > > > that > > > > > > > option. > > > > > > > > > > > > > > Yufei > > > > > > > > > > > > > > > > > > > > > On Tue, Feb 17, 2026 at 10:26 AM Dmitri Bourlatchkov < > > > > [email protected] > > > > > > > > > > > > > wrote: > > > > > > > > > > > > > > > Hi Robert, > > > > > > > > > > > > > > > > Excellent idea about leveraging the PR review process for > > proposal > > > > > > docs! > > > > > > > > > > > > > > > > I'm not sure we need to spend extra effort to publish > > proposals on > > > > > the > > > > > > > main > > > > > > > > site (unless it is easy :) ) as long as the contribution > guide > > is > > > > > clear > > > > > > > > about how to find them in GH. > > > > > > > > > > > > > > > > Once a proposal is implemented, the docs will naturally be > > updated > > > > > with > > > > > > > > corresponding user-facing instructions. > > > > > > > > > > > > > > > > Cheers, > > > > > > > > Dmitri. > > > > > > > > > > > > > > > > On Sun, Feb 15, 2026 at 8:41 AM Robert Stupp <[email protected] > > > > > > wrote: > > > > > > > > > > > > > > > > > Hi all, > > > > > > > > > > > > > > > > > > Mick brought up a very good point [1] about the use of > Google > > > > Docs > > > > > > for > > > > > > > > > proposals. > > > > > > > > > > > > > > > > > > Very simplified, our current proposal process is > > > > > > > > > - a contributor creates a Google Doc > > > > > > > > > - the proposal is introduced on [email protected] > > > > > > > > > - discussion happens on both the Google Doc and the dev@ > > mailing > > > > > > lists > > > > > > > > > > > > > > > > > > Google Docs are a great vehicle for collaboration. Just, I > > think > > > > > the > > > > > > > > > commentary functionality there is a bit odd. > > > > > > > > > There's also a "disconnect" (or "media break" if you prefer > > that > > > > > > term) > > > > > > > > > between the discussions that actually count and those that > > do not > > > > > > > (think: > > > > > > > > > "If it did not happen on the mailing list, it never > > happened.") > > > > > > > > > The valuable information in those Google Docs gets "lost", > as > > > > > there's > > > > > > > no > > > > > > > > > more direct relationship from the code or documentation to > a > > > > > proposal > > > > > > > and > > > > > > > > > the discussion that happened on it. > > > > > > > > > > > > > > > > > > We currently do not have a consistent overview of all > > proposals, > > > > > the > > > > > > > > > activity on those and their status. > > > > > > > > > > > > > > > > > > Technically speaking, proposals could fit pretty well into > > the > > > > > GitHub > > > > > > > > > pull-request workflow and, once accepted, serve as a > > reference, > > > > > > provide > > > > > > > > > insight into the agreed on ideas or even serve as > > documentation. > > > > > > > > > > > > > > > > > > What I am thinking of is a space on the web site that: > > > > > > > > > * lists the current proposals built from a query against > > open PRs > > > > > > with > > > > > > > > e.g. > > > > > > > > > the 'proposal' label, > > > > > > > > > * lists of closed proposals, closed PRs (dropped ideas or > > > > > > approaches), > > > > > > > > > * list of accepted proposals, merged PRs > > > > > > > > > > > > > > > > > > Moving proposals to PRs containing markdown (or asciidoc), > > would > > > > > > close > > > > > > > > the > > > > > > > > > "media break" and fix nicely with "it happened on the > mailing > > > > > list." > > > > > > > > > > > > > > > > > > I'd like to not go into the technical details or where the > > > > > proposals > > > > > > > > would > > > > > > > > > live in this discussion, but rather get your thoughts about > > the > > > > > idea > > > > > > in > > > > > > > > > general. > > > > > > > > > Just so much: GitHub has a good edit functionality with a > > live > > > > > > markdown > > > > > > > > > preview as a split view [2]. > > > > > > > > > > > > > > > > > > Cheers, > > > > > > > > > Robert > > > > > > > > > > > > > > > > > > > > > > > > > > > [1] > > > > > https://lists.apache.org/thread/dnvfck8owpz0z1n1f93mnjm2nlcjp3ym > > > > > > > > > [2] https://github.dev/apache/polaris/blob/main/README.md > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
