That seems fine to me, we can always tweak the process if it doesn't work as well as we think but using a PR and markdown makes it easy for anyone to contribute.
On Tue, Jan 7, 2025 at 8:42 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 > > >
