Apache How-To: Communicating Effectively

How can you be effective at asking questions or proposing changes at Apache or in an Apache project?  Besides making sure you use the right mailing list, and asking smart questions or following the several email etiquette guidelines and tips at Apache, what should you do to be effective at communicating your ideas?

There are plenty of times you’ve been polite and formulated a good question, but you either don’t get useful responses – or you get too many responses and tangents and complaints and and and…  What are some of the other factors to consider in being effective at communicating with Apache’s many communities?

Is this a question about one Apache project?

If your question or idea is just about a single Apache project, that’s pretty easy: write your thoughtful email to the dev@projectname mailing list; that’s where the primary community for most projects does their work.  Sometimes you may want to email the user@ mailing list if it’s a question about functionality, events, or user-based questions instead.

Make sure to understand that project’s expectations for discussions: do they use [SUBJECT-TAGS], or perhaps use JIRAs for organizing technical work?  Do they expect all proposals to be spelled out in your email, or do they often write up a proposal in their wiki, and then point to it from the email?  Following the project’s normal way of working is important to have maximum chance that other project volunteers will see and respond to your message.  Be sure to reply to any questions as well!

I can’t get a final decision on my question! What next?

The first thing is to be a little patient, and see if you can work out a good enough consensus.  That often takes time, because various other project participants may not see this as their urgent priority; you need to allow sufficient time for feedback.  You may need to adjust plans and make it clear that you’ve taken feedback and changed your proposal.

Sometimes, you need to call for a [VOTE].  The ASF has some very broad requirements around voting,  but really most of the details of votes are up to each individual PMC.  In most cases, a majority of +1 votes carries the day, unless -1 voters have a technically valid veto that can be shown to make the project worse (for a code modification).

Sometimes, if there is a larger issue at stake – where the dev@ list isn’t helping you at least get closure (even if it’s not necessarily agreement), you may want to escalate the issue to the PMC.  Every Apache project has a private@projectname mailing list – that’s privately archived – where the PMC discusses only issues that require privacy – typically security issues, voting in new committers, and rarely personnel issues or code of conduct type issues.

What if I have a question about the ASF itself?

The Apache Community Development project – with its own PMC and everything – is here to help guide newcomers and guide unusual questions to the right place.  If you have a public question about where to find someting, or that crosses multiple projects, start on the dev@community.apache.org mailing list.

Apache has a handful of other cross-project mailing lists as well for conferences, infrastructure, and legal questions.  Note that those lists are also publicly archived unless they specifically state otherwise.  Any potential security vulnerabilities should go directly to the Security Team, which obviously uses private archives.

What if an Apache project is not responding to me? How do I escalate concerns?

The ASF is designed to give project PMCs maximum freedom in governing their own projects.  While the board does expect to see a certain set of behaviors – especially working by consensus and welcoming any newcomers with good work, regardless of employer – the board of the ASF rarely gets involved directly in project operations.

However, if there is a serious governance or community issue that a PMC is not addressing, you can work to contact the ASF Board of DirectorsPMCs report quarterly directly to the board, separately from other corporate operations (infra, legal, trademarks, accounting, etc.)

Vulnerability escalations go to the Security team; and legal issues or communications from counsel go to the Legal Affairs committee.

How do I ask about Foundation governance and corporate affairs?

Most corporate organization happens on privately archived mailing lists.  While project work is done in the open as much as possible, internal corporate work like paying the bills, signing legal documents, and the like are done either by volunteers or in a few cases by paid staff or contractors.  The Membership of the ASF has oversight and visibility to these processes, and it’s usually Members who are volunteering to help with the work.

For Members, the first thing to remember is to use the right list!  Each area of corporate operations has their own mailing lists: legal, trademarks@, infrastructure, treasurer, fundraising, or secretary.  There’s also an overall operations mailing list that’s a great place to ask where you should take your question since the operations volunteers there usually have helpful answers.

PMC Members and committers don’t have access to those list archives, but we certainly accept emails from them. Be sure to send in a clear question, so we know you’re waiting for an answer, and we’ll get back to you.  If your question is about a specific Apache project, it’s a best practice to always cc: private@projectname as well, so the whole PMC there is aware.

If your question doesn’t require privacy, then the best bet is to ask Community Development to point you in the right direction.

What else can I do to be effective at communicating at Apache?

Remember: Apache mailing lists often have hundreds of subscribers – so you’re sending email to a lot of people, all of whom are (for Apache purposes) part-time volunteers.  Knowing your audience is one of the key points when writing – and that’s doubly true when communicating with so many people from different backgrounds.

  • Write helpful and descriptive subject lines; make sure list readers understand if they need to read your email – or not.
  • Keep email threads on topic – preferably, a single topic per email thread.  If you need to add a new topic or feel the urge to hijack someone’s thread, please don’t – start a new thread, or at least change the Subject line.
  • Pause. Take your time. Most project decisions should not be made in a rush, and overwhelming the list with your posts in a short period often backfires when other community members get overwhelmed and stop participating.
  • Keep focused on the issues, and the value to the project or to the ASF as a whole. Even about code we can sometimes feel emotional; keep it based on facts and focused on the big picture.
  • For significant decisions, re-post a recap of the final consensus.  This is best done with a new email or at least a changed Subject.
  • For complex issues, lay out the big picture very clearly.  Sometimes it’s best to post “Hey, I/we are thinking of $big_change_like_X.  If anyone already knows they’ll want to veto it, let us know before we investigate!”  Then write up a detailed proposal, and send that to the list for discussion.  Similarly: start a [DISCUSS] thread with the expectation to gauge interest and possible consensus, before doing lots of coding or planning work and assuming the project will accept it.

Still wondering where to ask something?  See my FAQ of FAQs about everything Apache too!