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

Reply via email to