Hi,
Why not using Github discussion for that?
Regards,
François
fpa...@apache.org
francois.pa...@openobject.fr
Le 12/12/2024 à 16:18, Jean-Baptiste Onofré a écrit :
Yeah, confluence would be an option, but I guess we would have the
same authentication pain as for Google Doc.
I prefer the proposal of Git/PR.
I wonder if we can't leverage the activemq-website repo with a folder
dedicated to design/proposal doc ?
Regards
JB
On Thu, Dec 12, 2024 at 4:10 PM Christopher Shannon
<christopher.l.shan...@gmail.com> wrote:
Design and discussions are good but I agree with no google docs and using
something else like Git.
The other option is to use Confluence but that is a pain because users need
new accounts to contribute which is hard to do.
Kafka uses Confluence for their KIPs for this purpose:
https://cwiki.apache.org/confluence/display/kafka/kafka+improvement+proposals
On Wed, Dec 11, 2024 at 12:36 PM Jean-Baptiste Onofré <j...@nanthrax.net>
wrote:
Hi Justin
I like the idea of the Git repo and PR/Jira.
We can experiment this, it sounds like a good process.
If no objection, I will create the activemq-design-docs repo.
Thanks
Regards
JB
On Wed, Dec 11, 2024 at 6:14 PM 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
