Agree with the process. Thanks for driving this! And FYI for people who are used to writing docs on Google doc, Google doc has this handy feature for converting into Markdown. Highlighting the text -> right click -> Copy as Markdown.
Thanks, Ken On Tue, Jan 7, 2025 at 7:21 AM Christopher Shannon < christopher.l.shan...@gmail.com> wrote: > 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 > > > > > > >
