adr: design discussions

[maxandersen]

proposal on how we can have more deliberate and consumable dev/design discussions

note: I'm on PTO 20-28th july so it will open at least that period. if no major objections/blockers apply it the week I'm back, thus early August.

[quarkus-bot]

Thanks for your pull request!

Your pull request does not follow our editorial rules. Could you have a look?

• title should preferably start with an uppercase character (if it makes sense!)
• description should not be empty, describe your intent or provide links to the issues this PR is fixing (using Fixes #NNNNN) or changelogs

_{This message is automatically generated by a bot.}

[maxandersen]

Suggested change

	- All posts we before did to quarkus-dev Mailing list should go to a category on the quarkus-dev/discussion
	* (pre)release announcement
	* ideas, suggestions, etc.

[cescoffier]

Fix a few typos.

As we discussed the content this morning, I don't have anything to add.

[emmanuelbernard]

I understand the reasoning but I personally do not like it.

Some points not addressed: any idea of content surviving GitHub going the Sourceforge way? i.e. archiving?

[dmlloyd]

Great!

[dmlloyd]

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.

[maxandersen]

I understand the reasoning but I personally do not like it.

got some alternative ?

Some points not addressed: any idea of content surviving GitHub going the Sourceforge way? i.e. archiving?

good point - I forgot to add that:

the current mailing list was stored in google groups - not sure if any alternate archive option there but at least those who received the emails have some copy of it.

github discussions have apis to access discussions that can be used for archiving.

Does that cover your concerns? if yes I'll add them.

[maxandersen]

Suggested change

	- All posts we before did to quarkus-dev Mailing list should go to a category on the quarkus-dev/discussion
	* (pre)release announcement
	* ideas, suggestions, etc.

[ebullient]

github discussions have apis to access discussions that can be used for archiving.

Another alternative is to have a bot user that is subscribed. This bot user could be the only allowed poster to the existing google group, which would mean all discussions + replies would still go to the group.

[holly-cummins]

FWIW, I find the idea of a repository with no executable code a bit awkward. It feels like we're letting the limitations of GitHub's notification granularity and our not-totally-adequate email filtering technology drive us into abusing the repository mechanism for something it wasn't really intended for.

I suspect we may have some problems with discoverability, in which not all quarkus contributors realise they need to subscribe to the new repo (for the same reason they may not realise they should subscribe to the existing mailing list). Should we lay out some success criteria and mitigations - for example, what proportion of contributors do we expect to subscribe to the new repo? Is our success criteria that there are more subscribers than we have on google groups? What do we do if people aren't subscribing, and we don't get more active discussions than we did in the current repo? How do we handle the situation where someone starts a contributor-oriented discussion on the main repo?

(I'm not saying any of those will happen, I'm just saying we should have a way of validating the approach is doing what we hope.)

[maxandersen]

FWIW, I find the idea of a repository with no executable code a bit awkward.

The repo will have documentation and possible minutes. It is IMO not a at all weird to have repos with just documentation.

It feels like we're letting the limitations of GitHub's notification granularity and our not-totally-adequate email filtering technology drive us into abusing the repository mechanism for something it wasn't really intended for.

I kind a get what you are saying here but I don't agree that this is not what the mechanism was intended for. It is super common to have multiple repositories for a project and do it way more finegrained - just look at quarkiverse or quarkusio in general :)

I think it is perfectly valid to have separation between user and dev/contributor conversations - common in past is *-user and *-dev email. Why aren't that all just on the same mailing list? because the surrounding tech/setup does not allow natural separation.

If you really wanna go for "perfect" then we could shut down quarkus github discussions and just make it Dev focused ....but then where does the users go?

I suspect we may have some problems with discoverability, in which not all quarkus contributors realise they need to subscribe to the new repo (for the same reason they may not realise they should subscribe to the existing mailing list).

Yes, I don't think that changes here - if anything the discussions are better as you can participate immediately where as with the mailing list you need to subscribe first.

Should we lay out some success criteria and mitigations - for example, what proportion of contributors do we expect to subscribe to the new repo? Is our success criteria that there are more subscribers than we have on google groups?

Don't think we have a way to see who are subscribed/getting notifications. do you know of a way?

What do we do if people aren't subscribing, and we don't get more active discussions than we did in the current repo?

we evaluate and consider options? it can't see how it get worse than current situation IMO where design discussion gets lost in main repo.

How do we handle the situation where someone starts a contributor-oriented discussion on the main repo?

Move it? (like we do when someone opens issue that should be discussion or vice-versa, or open issue in wrong repo)

[maxandersen]

github discussions have apis to access discussions that can be used for archiving.

Another alternative is to have a bot user that is subscribed. This bot user could be the only allowed poster to the existing google group, which would mean all discussions + replies would still go to the group.

not a fan - that would mean duplications of notifications/email for 1048 subscribers and risking missing actually accidental posts.

[holly-cummins]

I think it is perfectly valid to have separation between user and dev/contributor conversations - common in past is *-user and *-dev email. Why aren't that all just on the same mailing list? because the surrounding tech/setup does not allow natural separation.

I agree user and dev discussion should be separated. I'm just not 100% sure that "place you contribute to X" and "place you talk about your contributions to X" should be separated.

Don't think we have a way to see who are subscribed/getting notifications. do you know of a way?

I'm assuming we'd look at the watchers of the new repo. So, for the current repo we see:

That number does mixes in people who've just subscribed to discussions + issues and people who've subscribed to the whole firehose. So one advantage of a separate repo is we could see more clearly how many people were watching.

What do we do if people aren't subscribing, and we don't get more active discussions than we did in the current repo?

we evaluate and consider options? it can't see how it get worse than current situation IMO where design discussion gets lost in main repo.

That still feels like an email filtering problem, really. And a settings problem. People can subscribe to discussions at the moment:

So I think we're assuming we're optimising for people who want notifications for every PR and issue, but who do want to be able to filter the discussions out into their own pile. In the current scenario, the rule for Quarkus discussions is that [quarkusio/quarkus] is at the beginning of the subject line, and the text Discussion appears near the end of the subject line. And the rule isn't perfect, because it does mix together the user-focussed and contributor-focussed discussions.

With the proposal, the rule would be to look for [quarkusio/quarkus-dev], so it's a bit simpler because there isn't the AND in the rule ... and there would be no user discussion mixed in, which is clearly an advantage. At the moment user-focussed discussions are pretty low volume, but they are there - and we obviously hope they'll continue to increase in volume. :)

[holly-cummins]

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.

[ebullient]

we should also be prepared, GH Discussion spam happens, too.

[maxandersen]

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.

[holly-cummins]

That's a nice advantage, agreed.

[holly-cummins]

Suggested change

	Seperate quarkusio/quarkus-dev repository with discussions::
	Separate quarkusio/quarkus-dev repository with discussions::

[holly-cummins]

I have a suggestion: What if we called it quarkus-contrib? We see confusion with both the quarkus-dev google group and the #dev zulip channel, because every single one of our users is a developer, by definition. So people think "Awesome! I'm a Quarkus developer, this is the place for me!", and then we have to spend effort re-routing their queries. Using -contrib avoids this ambiguity.

[maxandersen]

I considered it but I when away from it as:

A) quarkus-contributors gets to be quite long and noisy in mail subject
B) "contrib" in many projects is additional stuff outside the main development
C) If worried about those used to quarkus-dev ml not discovering it reusing the name helps locate it via search.

WDYT ? Valid arguments ? Asking as I could be swayed both ways. B is my biggest worry but might just be from early days :)

[emmanuelbernard]

Some comments
on A : [quarkus/quarkus-dev] will already make it not very usable on mobile emails leaving 10 characters before it hides the rest of the email title.
On C, my personal importance meter rates this not too high

B is real and it adds up with GitHub discovery path difficulties to Discussions.

[maxandersen]

B is real and it adds up with GitHub discovery path difficulties to Discussions.

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?

[holly-cummins]

That's a good point about -contrib being used for 'extra' stuff. Using contrib for that kind of content is a silly name, IMO, but it's out there. So if the aim is to avoid ambiguity, then contrib is no good. So then contributors is my best suggestion, but I agree it's long. That's maybe not fatal. Another alternative is quarkus-design. Or quarkus-arch or quarkus-architecture, although that's a bit less differentiated from users, IMO.

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.

[holly-cummins]

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.
Assuming we don't migrate the content, we should add another disadvantage, which is that people either need to check the mailing list + main repo discussions to read historic discussions (increased fragmentation of 'where are discussions'), or we lose all of the historic discussions.

[maxandersen]

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 ?

[holly-cummins]

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.

[emmanuelbernard]

I understand the reasoning but I personally do not like it.

got some alternative ?

That's the difficulty but let me point down my concerns.

So far I've found GitHub notifications overwhelming to a point where I shut them all down.
Well almost all.
I had to set treasures of tricks and filters to get to a state where I receive too many but it is roughly on the acceptable realm. Still, between the flow, the awkward UX from email and the busy UI of Discussions, I naturally drop at least 2/3 of them.

So there are two concerns:

1. I personally fear I will not see all conversations despite being actively interested but not full time on Quarkus.
2. Which leads to me to all the other casual interested parties. Who can spend the time to fine tune the GitHub firehose just because Quarkus has their conversations in there ? How many will give up or not discover the conversation space in the first place because email or notification fine tuning in GitHub is simply not to the level it should be.

Like Holly, I find that we are adapting our flows to GitHub and that gives me an uneasy feeling.
Like we are mixing the tools with the way we want to operate (let's call it the process).
The mailing list is not where the key conversations are. That's 90% because as a process we have let die the notion of key conversation being centralized and the notion of bubbling up important choices from local convos to that centralized place. You can replace emails with hub and spoke pigeons networks but it won't change the fundamentals per se. The key choice is to force a hierarchical conversation aggregation and enforce it / keep it alive somehow.
Then you can discuss whether Discussion is significantly better than a mailing list. It tastes like a cart before horse situation.

Funny enough in other conversations, you pushed back on the idea of What vs How in ADRs but here there are two distincts levels

• What will be the communication process to ensure we solve discoverability and awareness for everyone including non full time contributors .
• how we implement that process (in this case changing to a new tool)

I feel really bad to throw this left ball now since the idea of a discussions based solution has been floating for quite a long time. But you asked to open up. Feel free to acknowledge and device to move on but this ask I think helped me to write down the two levels of uneasiness I have subconsciously felt.

To take a step back, looking at your decision drivers, I think the mailing list maybe fails the last point, the rest hits the mark.

On decision drivers I see open governance but I wonder whether you would want as goal

• to increase awareness and contributions for part time or casual contributors.
• general awareness of what is being worked on at a high level view so as not to miss key decisions while under moderate flow of data.

In this case, Discussions alone does not address the problem. It's a conjunction of process chosen and tools.

I'll stop there that's a long essay and not well articulated and see how poeple react.

Again sorry for that negative push after all the work pushed into it. I'll comply to whatever decision is taken in the end.

Some points not addressed: any idea of content surviving GitHub going the Sourceforge way? i.e. archiving?

good point - I forgot to add that:

the current mailing list was stored in google groups - not sure if any alternate archive option there but at least those who received the emails have some copy of it.

github discussions have apis to access discussions that can be used for archiving.

Does that cover your concerns? if yes I'll add them.

Yes we could archive via that api into some S3 bucket or file system and that would alleviate the archive concerns for me.

[maxandersen]

I think it is perfectly valid to have separation between user and dev/contributor conversations - common in past is *-user and *-dev email. Why aren't that all just on the same mailing list? because the surrounding tech/setup does not allow natural separation.

I agree user and dev discussion should be separated. I'm just not 100% sure that "place you contribute to X" and "place you talk about your contributions to X" should be separated.

That is how it is today - quarkus-dev mailing list is separate from where we place the contributions (quarkusio and quarkiverse organizations)

If I could do it all over I would when we opened up discussions made a quarkus-user repo with discussions and then use discussions in quarkus-dev for development.

But I haven't found a way to reverse it - and since the quarkus-dev conversations is not only about quarkusio/quarkus I'm personally not stressed out about having a separate repo for it.

Don't think we have a way to see who are subscribed/getting notifications. do you know of a way?

I'm assuming we'd look at the watchers of the new repo. So, for the current repo we see:

ah yes, watchers is probably decent approximation.

That number does mixes in people who've just subscribed to discussions + issues and people who've subscribed to the whole firehose. So one advantage of a separate repo is we could see more clearly how many people were watching.

yes.

What do we do if people aren't subscribing, and we don't get more active discussions than we did in the current repo?

we evaluate and consider options? it can't see how it get worse than current situation IMO where design discussion gets lost in main repo.

That still feels like an email filtering problem, really. And a settings problem. People can subscribe to discussions at the moment:

yes, and when you do it is completely impossible to filter them in any meaningful way. Hence why I have disabled Discussions notifcations for quarkusio currently and only read via web.

And is why I miss lot of the design conversations.

So I think we're assuming we're optimising for people who want notifications for every PR and issue, but who do want to be able to filter the discussions out into their own pile.

not sure I follow that rationale - I'm optimising for two things; being able to follow dev/design discussions without having user questions mixed in (and vice versa - i.e. users should not have to filter through dev conversations) and make it possible to follow it from both email and webui.

In the current scenario, the rule for Quarkus discussions is that [quarkusio/quarkus] is at the beginning of the subject line, and the text Discussion appears near the end of the subject line. And the rule isn't perfect, because it does mix together the user-focussed and contributor-focussed discussions.

With the proposal, the rule would be to look for [quarkusio/quarkus-dev], so it's a bit simpler because there isn't the AND in the rule ... and there would be no user discussion mixed in, which is clearly an advantage. At the moment user-focussed discussions are pretty low volume, but they are there - and we obviously hope they'll continue to increase in volume. :)

Yes, there is no way to filter/seperate.

note, what one look for is all the "X-GitHub" fields which lets you actually tag/sort in much more interesting ways :)

[holly-cummins]

If I could do it all over I would when we opened up discussions made a quarkus-user repo with discussions and then use discussions in quarkus-dev for development.

In that case a larger group of people would be affected by the counter-intuitive mechanism, so I'm glad we missed that opportunity. :) "If you have an issue, use this tab on this repo, but if you have a question, use this other tab on this other repo" would be hard for users to get right, and I suspect we'd have ended up doing a lot of "please don't talk about quarkus on the quarkus repo" traffic routing.

So I think we're assuming we're optimising for people who want notifications for every PR and issue, but who do want to be able to filter the discussions out into their own pile.

not sure I follow that rationale -

My thinking was that if people don't subscribe to the firehose of thequarkusio repo, then the email volume from subscribing to github discussions is low and manageable. So there's not really a problem for those emails - except that on the email interface, people would get notifications for both user and design discussions, at least until https://github.com/orgs/community/discussions/3951 is implemented.

I'm optimising for two things; being able to follow dev/design discussions without having user questions mixed in (and vice versa - i.e. users should not have to filter through dev conversations) and make it possible to follow it from both email and webui.

Possibly worth putting that in the ADR, near the top. It's more clearly aligned to the proposed solution than the intro we have, which is "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." (If the problem we're trying to solve is fragmentation of conversations, then adding a new place to have conversations gets us into https://xkcd.com/927/ territory. :))

If the problem we're trying to solve is a mechanism to have design conversations consumable by both email and web UI, while maintaining the separation of user and contributor conversations, then the conclusion follows a bit better.

[cescoffier]

@maxandersen Where are we on this?