In my opinion GitHub Discussions doesn't provide much more than what we already get with a [DISCUSS] thread on a mailing list. This format is great for a Q & A type format, but it's not really designed for evolving a document over time which is what I think we need from the design documentation process.
Justin On Thu, Dec 12, 2024 at 9:49 AM Francois Papon <francois.pa...@openobject.fr> wrote: > Hi, > > Why not using Github discussion for that? > > Regards, > > François > fpa...@apache.org > francois.pa...@openobject.fr > > Le 12/12/2024 à 16:18, Jean-Baptiste Onofré a écrit : > > 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 > > > > > > --------------------------------------------------------------------- > 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 > > >
