New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Maintainer-Guidelines: add communication section. #4020

Merged
merged 1 commit into from Apr 5, 2018

Conversation

Projects
None yet
6 participants
@MikeMcQuaid
Copy link
Member

MikeMcQuaid commented Apr 4, 2018

I'm proposing a change to the maintainer communication guidelines to steer us back into more public communication with one another. I've been guilty since we set up our Slack of letting technical conversations drift into there and posting comments like "as discussed in Slack". This strips the context for many of Homebrew's decisions from other maintainers, contributors and users and makes it harder to get involved with the project. Obviously I cannot (nor would I want to) force any other maintainers to adopt these guidelines but I think it's worth noting them for improved future communication.

I will follow up on this with trying to make more issues documenting high-level problems we're aiming to solve in Homebrew and PRs to document the roadmap for Homebrew.

CC @Homebrew/maintainers for review and thoughts.

@alyssais

This comment has been minimized.

Copy link
Contributor

alyssais commented Apr 4, 2018

I think that this will be a very good thing for the project. It should go a long way to let people feel invested in and valued by the project, and that they can contribute to the discussion.

- Homebrew's Slack/Discourse/GitHub repositories/other private communications
- Homebrew's Slack/Discourse/IRC/other direct 1:1 messages

All communication should ideally occur in public on GitHub. Where this is not possible (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs resolved) this move to maintainers' private communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications and all decisions made in a private communication should end up back as something linkable in GitHub.

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

that needs -> that needs to be

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

"this move to maintainers' private communication" <- some words are missing here

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

Technical decisions should not happen in 1:1 communications and all decisions made in a private communication should end up back as something linkable in GitHub.

This sentence contradicts itself.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs Fixed to clarify that if they happen (or have happened) they should end up on GitHub.

Maintainers have a variety of ways to communicate with each other:

- Homebrew's public repositories on GitHub
- Homebrew's Slack/Discourse/GitHub repositories/other private communications

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

The repetition between this line and the line that follows is confusing.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs Yeh; have reordered it a bit to make it a bit clearer


- Homebrew's public repositories on GitHub
- Homebrew's Slack/Discourse/GitHub repositories/other private communications
- Homebrew's Slack/Discourse/IRC/other direct 1:1 messages

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

You left off carrier pigeon.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs A glaring omission. Added!

@MikeMcQuaid MikeMcQuaid force-pushed the MikeMcQuaid:communication-guidelines branch from d80526c to 63ee455 Apr 4, 2018

- Homebrew's group communications between all maintainers on private channels (e.g GitHub/Slack/Discourse)
- Homebrew's direct 1:1 messages between two maintainers on private channels (e.g. iMessage/Slack/Discourse/IRC/carrier pigeon)

All communication should ideally occur in public on GitHub. Where this is not possible (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs to be resolved) this move to maintainers' private communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications but if they do or did they must end up back as something linkable in GitHub.

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

"this move to" is still missing words

- Homebrew's group communications between all maintainers on private channels (e.g GitHub/Slack/Discourse)
- Homebrew's direct 1:1 messages between two maintainers on private channels (e.g. iMessage/Slack/Discourse/IRC/carrier pigeon)

All communication should ideally occur in public on GitHub. Where this is not possible (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs to be resolved) this move to maintainers' private communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications but if they do or did they must end up back as something linkable in GitHub.

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

"do or did" is awkward

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs Have tweaked further

- Homebrew's group communications between all maintainers on private channels (e.g GitHub/Slack/Discourse)
- Homebrew's direct 1:1 messages between two maintainers on private channels (e.g. iMessage/Slack/Discourse/IRC/carrier pigeon)

All communication should ideally occur in public on GitHub. Where this is not possible (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs to be resolved) this move to maintainers' private communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications but if they do or did they must end up back as something linkable in GitHub.

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

are things "in GitHub" or "on GitHub"

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs Have used "on GitHub" consistently


- Homebrew's public repositories on GitHub
- Homebrew's group communications between all maintainers on private channels (e.g GitHub/Slack/Discourse)
- Homebrew's direct 1:1 messages between two maintainers on private channels (e.g. iMessage/Slack/Discourse/IRC/carrier pigeon)

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

this wording leaves 3-way direct messaging ambiguous

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs Have made unambiguous by clarifying the above to be more than two

@MikeMcQuaid MikeMcQuaid force-pushed the MikeMcQuaid:communication-guidelines branch from 63ee455 to 6948721 Apr 4, 2018

- Homebrew's group communications between more than two maintainers on private channels (e.g GitHub/Slack/Discourse)
- Homebrew's direct 1:1 messages between two maintainers on private channels (e.g. iMessage/Slack/Discourse/IRC/carrier pigeon)

All communication should ideally occur in public on GitHub. Where this is not possible (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs to be resolved) this can move to maintainers' private group communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications but if they do (or did in the past) they must end up back as something linkable on GitHub. For example, if a technical decision was made a year ago on Slack and another maintainer/contributor/user asks about it on GitHub that's a good chance to explain it to them and have something that can be linked to in future.

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

in future -> in the future

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

asks about it on GitHub -> asks about it on GitHub,

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs 👍 pushed.

@MikeMcQuaid MikeMcQuaid force-pushed the MikeMcQuaid:communication-guidelines branch from 6948721 to ceb80f7 Apr 4, 2018

- Homebrew's group communications between more than two maintainers on private channels (e.g GitHub/Slack/Discourse)
- Homebrew's direct 1:1 messages between two maintainers on private channels (e.g. iMessage/Slack/Discourse/IRC/carrier pigeon)

All communication should ideally occur in public on GitHub. Where this is not possible (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs to be resolved) this can move to maintainers' private group communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications but if they do (or did in the past) they must end up back as something linkable on GitHub. For example, if a technical decision was made a year ago on Slack and another maintainer/contributor/user asks about it on GitHub that's a good chance to explain it to them and have something that can be linked to in the future.

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

asks about it on GitHub -> asks about it on GitHub,

This comment has been minimized.

@MikeMcQuaid
Maintainers have a variety of ways to communicate with each other:

- Homebrew's public repositories on GitHub
- Homebrew's group communications between more than two maintainers on private channels (e.g GitHub/Slack/Discourse)

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

e.g -> e.g.

This comment has been minimized.

@MikeMcQuaid
@@ -55,7 +55,7 @@ If they accept, follow a few steps to get them set up:
- Add them to the [Jenkins' GitHub Authorization Settings admin user names](https://jenkins.brew.sh/configureSecurity/) so they can adjust settings and restart jobs
- Add them to the [Jenkins' GitHub Pull Request Builder admin list](https://jenkins.brew.sh/configure) to enable `@BrewTestBot test this please` for them
- Invite them to the [`homebrew-maintainers` private maintainers mailing list](https://lists.sfconservancy.org/mailman/admin/homebrew-maintainers/members/add)
- Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites)
- Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites) (and ensure they've read the [communication guidelines](Maintainer-Guidelines.md#communication))

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

should that be #Communication not #communication ?

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@ilovezfs from my testing #communication is correct/works.

This comment has been minimized.

@ilovezfs

ilovezfs Apr 4, 2018

Contributor

ok

@MikeMcQuaid MikeMcQuaid force-pushed the MikeMcQuaid:communication-guidelines branch from ceb80f7 to 35619cb Apr 4, 2018

- Homebrew's group communications between more than two maintainers on private channels (e.g. GitHub/Slack/Discourse)
- Homebrew's direct 1:1 messages between two maintainers on private channels (e.g. iMessage/Slack/Discourse/IRC/carrier pigeon)

All communication should ideally occur in public on GitHub. Where this is not possible (e.g. a security disclosure, interpersonal issue between two maintainers, urgent breakage that needs to be resolved) this can move to maintainers' private group communication and, if necessary, 1:1 communication. Technical decisions should not happen in 1:1 communications but if they do (or did in the past) they must end up back as something linkable on GitHub. For example, if a technical decision was made a year ago on Slack and another maintainer/contributor/user asks about it on GitHub, that's a good chance to explain it to them and have something that can be linked to in the future.

This comment has been minimized.

@maxim-belkin

maxim-belkin Apr 4, 2018

Contributor

I'd suggest adding something like 'or practical' after:

Where this is not possible

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@maxim-belkin good call, updated.

This comment has been minimized.

@reitermarkus

reitermarkus Apr 4, 2018

Member

But when is something “not practical”? You could pretty much argue that about anything.

This comment has been minimized.

@maxim-belkin

maxim-belkin Apr 4, 2018

Contributor

my comment was targeted at 'security issues' and 'urgent breakage': it is not practical to discuss them in public, meaning, it does not make a lot of sense to do that.

The same somewhat applies to interpersonal issues, though I wouldn't call them out here.

This comment has been minimized.

@reitermarkus

reitermarkus Apr 4, 2018

Member

Can we change it to “appropriate”? This meaning of “practical” isn't the first thing I would think of as a non-native speaker.

This comment has been minimized.

@MikeMcQuaid

MikeMcQuaid Apr 4, 2018

Member

@reitermarkus Agreed, pushed.

This comment has been minimized.

@maxim-belkin

maxim-belkin Apr 4, 2018

Contributor

appropriate is appropriate

@MikeMcQuaid MikeMcQuaid force-pushed the MikeMcQuaid:communication-guidelines branch from 35619cb to 4a02283 Apr 4, 2018

Maintainer-Guidelines: add communication section.
Note the best ways for maintainers to communicate with each other.

@MikeMcQuaid MikeMcQuaid force-pushed the MikeMcQuaid:communication-guidelines branch from 4a02283 to a12b539 Apr 4, 2018

@ilovezfs
Copy link
Contributor

ilovezfs left a comment

Obviously I cannot (nor would I want to) force any other maintainers to adopt these guidelines but I think it's worth noting them for improved future communication.

Given this statement, the language in this PR is overly prescriptive and imperative:

All communication should ideally occur in public on GitHub

Technical decisions should not happen in 1:1 communications

they must end up back as something linkable on GitHub

@MikeMcQuaid

This comment has been minimized.

Copy link
Member

MikeMcQuaid commented Apr 5, 2018

Obviously I cannot (nor would I want to) force any other maintainers to adopt these guidelines but I think it's worth noting them for improved future communication.

Given this statement, the language in this PR is overly prescriptive and imperative

By my statement I mean I cannot force maintainers from chatting with each other about whatever they choose (including technical decisions) on iMessage/Slack. I can however state that no maintainer should accept "discussed on Slack" as an adequate justification for a current or existing decision and that any maintainer can point to these guidelines as a reason they are unwilling to have a technical discussion on iMessage/Slack.

@ilovezfs

This comment has been minimized.

Copy link
Contributor

ilovezfs commented Apr 5, 2018

In that case, I see them as overly burdensome and don't think always explaining things on GitHub is a great use of maintainer time.

@MikeMcQuaid

This comment has been minimized.

Copy link
Member

MikeMcQuaid commented Apr 5, 2018

In that case, I see them as overly burdensome and don't think always explaining things on GitHub is a great use of maintainer time.

I'm not willing to continue to reach technical decisions in a place that cannot be seen by other Homebrew maintainers, contributors or users. By the looks of the reaction to this PR I'm not the only maintainer who feels this way. So long as we have one maintainer who wants to discuss a technical decision outside of Slack: this is unavoidable.

We're an open source project. We need to be open to input from other maintainers, contributors and users on our decisions and we owe it to all of them to at least to be able to point to the discussion that lead to a decision.

@MikeMcQuaid

This comment has been minimized.

Copy link
Member

MikeMcQuaid commented Apr 5, 2018

It's been 24h and this has 2 , 3 maintainers 👍 and 3 maintainers ❤️ so: merging. Feel free to leave additional comments and I'll address then in follow-up PRs.

@ilovezfs

This comment has been minimized.

Copy link
Contributor

ilovezfs commented Apr 5, 2018

We're an open source project. We need to be open to input from other maintainers, contributors and users on our decisions and we owe it to all of them to at least to be able to point to the discussion that lead to a decision.

Yes, that makes sense.

@MikeMcQuaid MikeMcQuaid merged commit 94c0d83 into Homebrew:master Apr 5, 2018

3 checks passed

codecov/patch Coverage not affected when comparing 1376b9e...a12b539
Details
codecov/project 70.13% remains the same compared to 1376b9e
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@MikeMcQuaid MikeMcQuaid deleted the MikeMcQuaid:communication-guidelines branch Apr 5, 2018

@fxcoudert

This comment has been minimized.

Copy link
Member

fxcoudert commented Apr 5, 2018

I'd like to add that in many cases, I have been able to educate myself (as a new maintainer) from discussion and justifications found in older pull requests, as to the choices that were made at the time. So this is definitely a win for all future maintainers.

@lock lock bot added the outdated label May 5, 2018

@lock lock bot locked as resolved and limited conversation to collaborators May 5, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.