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