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