> ...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 > > >
