Hey folks, Could we create a place for holding design docs as a first step? I have a few pending design docs ready for review and potentially we can use that to test the new proposal as well. WDYT?
Thanks, Ken On Wed, Jan 8, 2025 at 7:56 AM Matt Pavlovich <mattr...@gmail.com> wrote: > Sounds good > > > On Jan 7, 2025, at 7:41 AM, Jean-Baptiste Onofré <j...@nanthrax.net> > wrote: > > > > Hi > > > > I think so, the final proposal is: > > > > - we describe the design document is using markdown > > - we create a PR on the main repo containing the markdown, adding > > design folder (for ActiveMQ Classic, the PR would be based on > > https://github.com/apache/activemq in a design folder) > > - the review and comments are discussed directly in the PR where we > > "enrich" the design > > - when a consensus is reached, the PR is merged and another PR for > > implementation can start > > > > Thoughts ? > > > > I plan to open a first PR using this process for receiveBody(). > > > > Regards > > JB > > > > On Tue, Jan 7, 2025 at 1:31 PM Christopher Shannon > > <christopher.l.shan...@gmail.com> wrote: > >> > >> Did we come to a consensus on where to put the design docs? It looks > like a > >> Git repo was favored but not sure we ever came up with a spot for it or > >> decided where things should be. > >> > >> On Sat, Dec 21, 2024 at 1:33 AM Jean-Baptiste Onofré <j...@nanthrax.net> > >> wrote: > >> > >>> Hi, > >>> > >>> To illustrate that, as I've started to work on receiveBody() > >>> implementation, before opening the PR, I will draft a design proposal > >>> for receiveBody() and use the process we discussed here. > >>> We will be able to "adapt" the process if needed. > >>> > >>> I will keep you posted. > >>> > >>> Regards > >>> JB > >>> > >>> On Fri, Dec 20, 2024 at 8:54 PM Justin Bertram <jbert...@apache.org> > >>> wrote: > >>>> > >>>>> ...when I say “users”— Developers extending the product are also > >>> “users” > >>>> here, not just app teams sen/recv messages. > >>>> > >>>> I was thinking of the same class of users. > >>>> > >>>>> As most features (in ActiveMQ Classic) have extension points, having > >>>> these design docs included in the hosted documentation is a way to > >>> benefit > >>>> that class of users. > >>>> > >>>> Instead of out-of-band implementation design docs I would suggest > robust > >>>> API/SPI docs in the code (e.g. JavaDoc) to give this class of > >>>> developers/users all the information they need to extend the broker. > This > >>>> is an industry standard and what most Java developers would expect. > >>>> > >>>> Ultimately my concern here is to mitigate the proliferation of > technical > >>>> debt. This website is already chock full of well intentioned docs that > >>> were > >>>> relevant at the time but slowly fell out of date and now represent a > >>>> maintenance burden. > >>>> > >>>>> I think it would be confusing and counter productive to host design > >>>> documents for both brokers in the same repo. This would be really > >>> confusing. > >>>> > >>>> It seems pretty straight-forward to me as long as the directories are > >>>> clearly labeled. After all, the website contains info about both > brokers > >>>> (and every other component), and it's just one repo. Folks don't seem > to > >>>> have trouble with that, but maybe I'm wrong. > >>>> > >>>> > >>>> Justin > >>>> > >>>> > >>>> On Wed, Dec 18, 2024 at 10:39 AM Matt Pavlovich <mattr...@gmail.com> > >>> wrote: > >>>> > >>>>> Let me clarify when I say “users”— Developers extending the product > are > >>>>> also “users” here, not just app teams sen/recv messages. > >>>>> > >>>>> As most features (in ActiveMQ Classic) have extension points, having > >>> these > >>>>> design docs included in the hosted documentation is a way to benefit > >>> that > >>>>> class of users. > >>>>> > >>>>> I think it would be confusing and counter productive to host design > >>>>> documents for both brokers in the same repo. This would be really > >>>>> confusing. Having Artemis design docs in the Artemis docs source area > >>> and > >>>>> the Classic design docs in the classic doc repo area would seem to > make > >>>>> sense to avoid confusion. > >>>>> > >>>>> Matt Pavlovich > >>>>> > >>>>>> On Dec 12, 2024, at 12:38 PM, Justin Bertram <jbert...@apache.org> > >>>>> wrote: > >>>>>> > >>>>>> I'm not sold on the "user-accessible documentation" aspect of this. > >>>>>> Documenting design in enough detail to actually help developers > >>> implement > >>>>>> the design is, in my experience, not great for user docs. > >>> Furthermore, it > >>>>>> introduces a maintenance burden because if future code updates alter > >>> the > >>>>>> design then corresponding documentation updates will be necessary in > >>>>> order > >>>>>> to keep them relevant. > >>>>>> > >>>>>> The more detailed the design document is the more helpful it will be > >>> to > >>>>> the > >>>>>> developer implementing that design, but the more of a burden it will > >>> be > >>>>> if > >>>>>> incorporated into user docs. This is not dissimilar to comments in > >>> code > >>>>>> which slowly fall out of date as the code evolves. Eventually the > >>> comment > >>>>>> is confusing and hurts more than helps. > >>>>>> > >>>>>> At this point I would consider these design docs as categorically > >>>>> different > >>>>>> from code and user documentation so I wouldn't welcome them in the > >>>>>> respective Git repo of the component. I think a separate repo makes > >>> more > >>>>>> sense. > >>>>>> > >>>>>> > >>>>>> Justin > >>>>>> > >>>>>> On Thu, Dec 12, 2024 at 12:04 PM Matt Pavlovich <mattr...@gmail.com > > > >>>>> wrote: > >>>>>> > >>>>>>> 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 > >>>>>>> > >>>>>>> > >>>>>>> > >>>>> > >>>>> > >>>>> --------------------------------------------------------------------- > >>>>> 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 > > >
