Hi Ken I propose to use PR on activemq website, using docs folder (https://github.com/apache/activemq/tree/main/docs/). Let's start by creating a proposals folder inside docs and add md documents there in a PR.
Thoughts ? Regards JB On Mon, Feb 17, 2025 at 6:52 PM Ken Liao <kenlia...@gmail.com> wrote: > > 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 > > > > > > --------------------------------------------------------------------- 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
