Hi JB, Sounds awesome! I will go ahead and create those PRs :)
Thanks, Ken On Mon, Feb 17, 2025 at 12:02 PM Jean-Baptiste Onofré <j...@nanthrax.net> wrote: > 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 > > >
