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


Reply via email to