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
