Yeah, confluence would be an option, but I guess we would have the same authentication pain as for Google Doc.
I prefer the proposal of Git/PR. I wonder if we can't leverage the activemq-website repo with a folder dedicated to design/proposal doc ? Regards JB On Thu, Dec 12, 2024 at 4:10 PM Christopher Shannon <christopher.l.shan...@gmail.com> wrote: > > Design and discussions are good but I agree with no google docs and using > something else like Git. > > The other option is to use Confluence but that is a pain because users need > new accounts to contribute which is hard to do. > > Kafka uses Confluence for their KIPs for this purpose: > https://cwiki.apache.org/confluence/display/kafka/kafka+improvement+proposals > > On Wed, Dec 11, 2024 at 12:36 PM Jean-Baptiste Onofré <j...@nanthrax.net> > wrote: > > > Hi Justin > > > > I like the idea of the Git repo and PR/Jira. > > > > We can experiment this, it sounds like a good process. > > > > If no objection, I will create the activemq-design-docs repo. > > > > Thanks > > Regards > > JB > > > > On Wed, Dec 11, 2024 at 6:14 PM 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 > > > > > > --------------------------------------------------------------------- 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
