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