adr: design discussions #41973
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,125 @@ | ||||||
| = Setup of Development Discussions | ||||||
|
|
||||||
| * Status: proposed | ||||||
| * Date: 2024-07-18 | ||||||
|
|
||||||
| == Context and Problem Statement | ||||||
|
|
||||||
| Currently development discussions happens in a variety of places, including the mailing list, zulip, github issues, pull-requests, discussions, calls etc. | ||||||
|
|
||||||
| Its awesome that we have so many ways to communicate, but it also makes it difficult to find the information you need or being able to at least follow certain areas. | ||||||
|
|
||||||
| This ADR proposes to have a more structured way of having development discussions, so that it is easier to find and follow such discussions. | ||||||
|
|
||||||
| == Decision Drivers | ||||||
|
|
||||||
| * Enable better open governance | ||||||
| * Prefer async over sync communication | ||||||
| * Avoid requiring to subscribe to a "raging river" of notifications that is not filterable | ||||||
| * Allow use of e-mail as not everyone can/will use web-ui | ||||||
| * Have consistent place to publish and lookup Quarkus development ideas/suggestions | ||||||
|
|
||||||
| == Scenarios | ||||||
|
|
||||||
| For a Quarkus core developer, where do they best post ideas for suggestion and feedback? Zulip chat? Open an issue? Submit a PR directly? Post to quarkus-dev? Open a GitHub discussion? Use private chat? Today all of the above happens based on habit or specific requests. | ||||||
|
|
||||||
| A dev interested in doing contributions by following the ongoing conversations - which of the many channels do they follow? | ||||||
|
|
||||||
| == Considered options | ||||||
|
|
||||||
| Primarily use quarkus-dev mailing list:: | ||||||
| Advantages:::: | ||||||
| * well-known and understood by most if not all existing Quarkus contributors (~1000+ subscribers) | ||||||
| * can post, comment and read with any e-mail client | ||||||
| * filters out most noise as people need to subscribe | ||||||
| Disadvantages:::: | ||||||
| * over time it has died out, rarely where conversations starts/continues being discussed | ||||||
| * e-mail/google groups is just not where new people show up as much now | ||||||
| * requires subscribing to specific list to post | ||||||
| * spam (fixed now by moderation) | ||||||
| * arbitrary blocking of mails (specifally @gsmet and others) | ||||||
|
|
||||||
| Primarily have "Design Discussions" a sub-category of Quarkus Community/User Discussions:: | ||||||
| Advantages:::: | ||||||
| * Centralized location for discussions, anyone sees it | ||||||
| * Anyone can read | ||||||
| * Anyone with GitHub account can post/reply | ||||||
| * Moderation tools available to battle spam/noise | ||||||
| Disadvantages:::: | ||||||
| * Notifications via email comes for *all* discussions, not possible to choose specific category | ||||||
|
There was a problem hiding this comment. As a note, you can turn off email notifications and use the GitHub notifications panel instead. I've done this and it has been very helpful in controlling email volume. |
||||||
| * User forums gets intermixed with Developer/Design discussions | ||||||
|
|
||||||
| Primarily use issues/PR's:: | ||||||
| Advantages:::: | ||||||
| * Conversation directly linked to code changes | ||||||
| Disadvantages:::: | ||||||
| * Not possible to just monitor the overall design discussions as all mixed up with anything else | ||||||
| * Notification filtering is quite limited | ||||||
maxandersen marked this conversation as resolved.
Show resolved
Hide resolved
maxandersen marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| * Limited threading in webui | ||||||
| * No-threading on email responses | ||||||
|
|
||||||
| Primarily use Zulip Chat:: | ||||||
| Advantages:::: | ||||||
| * Real-time communication | ||||||
| Disadvantages:::: | ||||||
| * Only for those who have time/privilege to follow along | ||||||
|
|
||||||
| Use private chat/mail:: | ||||||
| Advantages:::: | ||||||
| * Direct and focused private communication (sometimes useful) | ||||||
| Disadvantages:::: | ||||||
| * Not great for open governance unless culture to comment/report on conclusion somewhere more public | ||||||
| * Cannot be located/found when trying to search for answers/why something was done | ||||||
|
|
||||||
| Status quo/Do nothing:: | ||||||
| Advantages:::: | ||||||
| * Nothing need to change | ||||||
| Disadvanteges:::: | ||||||
| * All of the above disadvantages | ||||||
| * No clear place to go for design discussions | ||||||
|
|
||||||
| Seperate quarkusio/quarkus-dev repository with discussions:: | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. I have a suggestion: What if we called it There was a problem hiding this comment. I considered it but I when away from it as: A) quarkus-contributors gets to be quite long and noisy in mail subject WDYT ? Valid arguments ? Asking as I could be swayed both ways. B is my biggest worry but might just be from early days :) There was a problem hiding this comment. Some comments B is real and it adds up with GitHub discovery path difficulties to Discussions. There was a problem hiding this comment.
not sure I follow ? I read it as yes, its problematic to use "-contrib" as it has a specific meaning but then i missed your point on how that connects to discovery path difficulties to discussions? There was a problem hiding this comment. That's a good point about I think @emmanuelbernard's point is that the discovery experience for the new repo won't be great. It won't be the first place people will expect to find design discussions, they're going to need to be directed to it. If the name of the repo looks like it holds additional stuff outside the main development, then it's even harder for people to land in the right place when they want to talk design. |
||||||
| Advantages:::: | ||||||
| * Clear place to go for design discussions | ||||||
| * Easy to find and follow discussions | ||||||
| * Can filter/focus separately on user versus developer discussions | ||||||
| * Can use e-mail, at least for commenting | ||||||
| * ADR can be moved there | ||||||
| * Future call minutes can be moved there | ||||||
| * Does not break existing user conversations | ||||||
| Disadvantages:::: | ||||||
| * Need to move discussions from other places to this new place | ||||||
|
There was a problem hiding this comment. Is "move" here a move of actual content, or just a move of people's habit? It would be nice to move the content so that people don't have to look in all the old places for old content, post-move, but I'm not sure of a mechanism that could do that. There was a problem hiding this comment. I was thinking about the move of people not content here. I didn't consider copying in all the Quarkus dev posts from the last 5 years into the discussions as I don't know of a way to do it efficiently and with proper date. Got ideas ? Is it necessary ? There was a problem hiding this comment. It depends what problem we're trying to solve. If we don't do some sort of migration, we're trading off increased fragmentation of information (people looking for information have to look in more places, because the information might be in an old email/discussion-in-the-wrong-repo) against a better experience going forward (we get to use the github discussions interface without user-conversation contamination). Maybe that's an ok tradeoff. |
||||||
| * Need to retire quarkus-dev mailing list | ||||||
| * Users conversation is in the repo where code is, developer conversation is in a separate repo | ||||||
|
|
||||||
| == Decision | ||||||
|
|
||||||
| - Introduce a new GitHub repository called `quarkusio/quarkus-dev`. | ||||||
| * Have a README with links to discussions, ADRs, call minutes etc. | ||||||
| * Enable discussions in the repository | ||||||
| * Use @quarkus-bot for tagging | ||||||
| - Move/Close existing "Design Discussions" to the new repository | ||||||
| - Move existing quarkusio/quarkus ADRs to the new repository | ||||||
maxandersen marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| * keep `adr` directory in the main repository with a README pointing to the new location | ||||||
| - Retire `quarkus-dev` mailing list | ||||||
| * Add a footer to all mails with a message to go to the new repository | ||||||
| * Change the name of the mailing list to `quarkus-dev-retired` | ||||||
| * Post last e-mail to the list with a message to go to the new repository | ||||||
| * Eventually (6-12 months?) enable moderation | ||||||
| ** not doing it on day one as it will take a while for 1000+ members to get the message | ||||||
| - Encourage moving Zulip chat introducing/tracking ideas to discussions | ||||||
| * Encourage summarizing chat outcomes on discussions/issues | ||||||
| * Rename `#dev` channel to `#contributors` | ||||||
| == Consequences | ||||||
|
|
||||||
| - Can no longer use e-mail cc's to add people into conversatiion. Use @'s to mention github user and if needed forward link to user who are not on github. | ||||||
|
|
||||||
| - Starting a thread must be done via web-ui; comments and notifications will work with standard mail. | ||||||
|
|
||||||
| - move discussion to issue ends up in quarkus-dev, not quarkus repo | ||||||
| - automate move with bot moving if certain label added? (to be discussed) | ||||||
|
|
||||||
| == Related decisions | ||||||
|
|
||||||
| - link:0001-community-decision-making.adoc[] | ||||||
| - https://quarkus.io/blog/quarkus-in-a-foundation/[Moving Quarkus to a Foundation] | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should also mention that there's a steady stream of user questions on the quarkus-dev mailing list, and every time it happens one of us has to reply to point out it's not a mailing list for users.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we should also be prepared, GH Discussion spam happens, too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would not call it a "steady stream". It's been reduced greatly ever since we more consistently redirect. But yes it happens.
Advantage of GitHub discussions here is we can transfer issues to the right place without the poster having to resend.
I'll add that to list.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a nice advantage, agreed.