I like the idea of git — one thought— could we simply use the sub-project code repo associated for the project? This would allow for keeping the design/dev docs near the code and automatically create user-accessible documentation in a two-for-one.
Example: docs/design/ <— place markdown, asciidoc or whatever here Thanks, Matt > On Dec 11, 2024, at 11:14 AM, Justin Bertram <jbert...@apache.org> wrote: > > 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 >> >> >> --------------------------------------------------------------------- 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
