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
