I'm with Matt here. It would be good to have a more robust process for developing design documents, but I'm not in favor of Google Docs for this.
I actually think we already have a great tool for this - Git. We can create a new Git repo (e.g. named activemq-design-docs). When we create a Jira that needs a corresponding design doc we can create a new directory in that Git repo with a name corresponding to the Jira. In that directory we can add documentation, images, and whatever other assets we need. Both MarkDown and AsciiDoc are sufficiently feature rich to capture complex ideas. When the pull request for the document is created folks can comment inline, request changes, etc. The author can request reviews from specific folks (if necessary). It can be held in "draft" state until complete if necessary. The link to the PR can be automatically added to the Jira (i.e. via ASF Infra integration) and comments on the PR will be reflected on the Jira and on the relevant mailing list. The resulting document will be clearly and publicly available and will be able to evolve over time even after the first commit is merged. Just keep adding commits and discussions until everything is sorted - just like the source code and documentation we already work with. Folks are already familiar with this process and these tools. I think this would also eliminate any strict need for a [DISCUSS] thread. We already have long discussions on PRs that don't have a corresponding [DISCUSS] thread so doing this for design docs would just be business as usual. Thoughts? Justin On Tue, Dec 10, 2024 at 1:29 PM Matt Pavlovich <mattr...@gmail.com> wrote: > +1 for the design discussion / document approach vs JIRA. > > -1 on using Google Docs — I’m not in favor of adding yet-another-tool. How > about something like GH discussions? or some other capability already > available to Apache projects. Adding Google introduces a whole new > authentication/authorization/identity system. > > We could then slightly alter the [DISCUSS] process to be — announce on dev@ > via [DISCUSS] subject that a new discussion is taking place on GH > discussions (or whatever other tool) and provide the link. > > Thanks! > Matt Pavlovich > > > On Dec 10, 2024, at 10:59 AM, Jean-Baptiste Onofré <j...@nanthrax.net> > wrote: > > > > Hi folks, > > > > We recently discussed several proposals (SemVer in ActiveMQ, new > > Jakarta Message 3 support in Classic, upgrade Artemis minimum Java > > version, ...). > > > > I would like to propose a "process" to: > > - discuss "long" designs > > - track proposals > > - facilitate collaborative contributions > > > > The process proposal is the following: > > - the contributors work on a design proposal. This document should: > > a. provide a rationale and what problems are solved > > b. provide abstract design with context > > c. clearly describe design options with implementations details > > (optionally pseudo code) > > The document is a Google Document, where anyone can comment. > > - the Google Document link is attached to the corresponding Jira. The > > Jira should have the "proposal" tag. > > - the Google Document link is sent to the dev mailing list (with a > > quick description of the proposal) > > - If needed, the Google Document "leader" can schedule a meeting > > (Google Meet) to discuss details and clarify design options. This > > meeting should be recorded (or at least notes should be taken). The > > design document should be updated after the meeting, and the meeting > > notes should be shared either to update the design document or on the > > dev mailing list. > > > > It's a process used in several Apache projects (Apache Iceberg, Apache > > Polaris, Apache Arrow, ...) and it works pretty fine. > > > > Thanks to that: > > 1. we can track all proposals Jira we have (basically populated our > roadmap) > > 2. before implementing, we can collaborate on design using the Google > Document > > 3. we should have a better collaboration, especially on complex > > design/implementation > > > > For instance, I would like to illustrate the process with Jakarta > > Messaging 3.1 Shared Subscription. We know this feature is not trivial > > and requires a clean design before rushing on the code/implementation. > > So, we can start with a design Google Document, attached to > > https://issues.apache.org/jira/browse/AMQ-8323 and send the design > > document on the dev mailing list. > > Then, we start contributing to the document, adding comments with > > questions or suggestions. > > The purpose is to reach a consensus on the design before actually > > starting the implementation. > > > > Thoughts ? > > > > Regards > > JB > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@activemq.apache.org > > For additional commands, e-mail: dev-h...@activemq.apache.org > > For further information, visit: https://activemq.apache.org/contact > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@activemq.apache.org > For additional commands, e-mail: dev-h...@activemq.apache.org > For further information, visit: https://activemq.apache.org/contact > > >
