How to use mailing lists and other communication tools responsibly

Overview

This guide explains how Apache projects maintain open, archived, and inclusive communication, as well as how to use modern tools responsibly alongside traditional mailing lists.

Communication is at the heart of every Apache project. Mailing lists remain the primary and required channel because they ensure that decisions are recorded, archived, and accessible to everyone, now and in the future. Other tools, such as chat platforms, GitHub Discussions, and video meetings, can support collaboration, but they should complement mailing lists rather than replace them.

All Apache mailing lists are publicly searchable and archived at lists.apache.org, ensuring discussions remain discoverable long after they occur.

English Used in Communication

All public communication within Apache projects, including on mailing lists, in issue trackers, and in release or vote discussions, should be conducted in English.
This ensures that all participants across the global ASF community can read, respond to, and audit project discussions and decisions.

While contributors are welcome to collaborate informally in other languages (for example, through local meetups or private chats), any outcomes that influence technical direction, governance, or community decisions must be summarised and recorded in English on the appropriate public mailing list.

Reasons why:

• Transparency: Using a single shared language ensures that discussions and decisions are visible and understandable to all community members, mentors, and the ASF as a whole.
• Inclusivity: English serves as the common working language across ASF projects, enabling participation from contributors worldwide regardless of native language.
• Auditability: ASF governance relies on archived public communication. Conducting key discussions in English ensures that project history remains accessible and reviewable.
• Consistency: A shared language avoids discussion fragmentation and reduces the risk of misunderstandings caused by partial or untranslated communication.

Why the ASF Uses Mailing Lists

From its earliest days, the Apache Software Foundation has used publicly archived mailing lists as the backbone of project communication.
This approach reflects ASF’s core principles of openness, independence, and long-term sustainability.

Key reasons:

1. Open Participation
   Anyone with an email address can join the conversation. You don't need any invitations, accounts, or proprietary tools.

2. Transparency and Accountability
   Mailing lists create a public, permanent record of every discussion and decision. This openness builds trust and helps others understand how and why choices are made.

3. Asynchronous Collaboration
   Contributors across different time zones can participate at their convenience. No one is excluded for being offline during a meeting.

4. Independence and Continuity
   ASF mailing lists are hosted by the Foundation, ensuring that project history remains intact and accessible for future contributors.

In short:

Mailing lists embody ASF’s principle that “if it didn’t happen on the list, it didn’t happen.”

How Projects Should Use Mailing Lists

Mailing lists are the foundation of transparent governance and community growth in every Apache project.

1. Record of Project Life

• All meaningful technical and governance discussions take place on the public dev@ list.
• Votes, releases, and decisions belong here so they can be archived and reviewed.

2. Building Consensus

• Lists support thoughtful, asynchronous discussion where everyone has a voice.
• This helps communities reach an agreement through open conversation rather than relying on speed or authority.

3. Public Accountability

• Mailing lists make project activity visible and verifiable.
• Mentors, PMCs, and the ASF Board can confirm that a community operates transparently.

4. Supporting Different Audiences

• Most projects maintain both a dev@ list for contributors and a user@ list for questions and support.
• Encouraging user questions on user@ helps keep dev@ focused on development and governance topics.

Private Mailing Lists

Every ASF project also has a private@ list, used only for confidential topics, such as new committer or PMC nominations, security issues, or concerns regarding personal conduct.
All technical and community discussions should remain public on the dev@ mailing list. Private lists should never be used for day-to-day development or decision-making.

Using Other Communication Tools Responsibly

Alternative tools can help with coordination and community building, provided they are used openly and summarized back to the mailing list.

Chat Platforms (e.g., Slack, Matrix, Discord, WeChat)

Good for:

• Quick coordination and informal discussion
• Helping new contributors or answering questions
• Social interaction and team building

Guidelines:

• Don’t make technical or policy decisions in chat.
• Summarize meaningful discussions back to dev@.
• Avoid exclusive or private groups that fragment the community.
• Keep a public record or project wiki link to the chat for visibility.

Example:

“We discussed improving the release checklist on Slack — a draft will be shared on dev@ for feedback.”

GitHub Discussions

GitHub Discussions are useful for community Q&A, design brainstorming, or gathering feedback, if managed transparently.

Good for:

• User support and troubleshooting
• Early design ideas or proposal drafts
• Discussing new features before formal votes

Guidelines:

• Don’t make binding decisions solely in GitHub Discussions.
• Forward or summarize key discussions to dev@.
• Use clear titles and categories for easy navigation.
• Avoid shifting essential decision-making off the list.

Example:

“There’s a GitHub Discussion on authentication support — summarizing key points here so the full community can weigh in on dev@.”

Tip:
GitHub Discussions can be configured to automatically send new threads to dev@ using asf.yaml. Enabling this keeps discussions visible and archived with the rest of project communication.

Video or Voice Meetings (e.g., Zoom, Google Meet, Jitsi)

Meetings can strengthen collaboration, especially for distributed teams, but they should support, not replace, mailing list communication.

Good for:

• Regular weekly or monthly community syncs
• Planning releases or coordination across time zones
• Mentoring or complex design discussions

Best Practices:

• Announce meetings in advance on dev@ (include date, time, agenda, and link).
• Keep meetings open to all interested contributors.
• Record or take concise notes whenever possible.
• Post a short summary or minutes on dev@.
• Rotate times to include different regions.

Decisions:
All proposals, votes, and resolutions must still happen on the mailing list.

Example:

“In today’s community sync, we agreed to delay RC1 by one week — please confirm or object on dev@.”

Common Mistakes to Avoid

• Making or recording project decisions in chat, GitHub Discussions, or meetings.
• Keeping invite-only or closed channels for general discussions.
• Forgetting to summarize off-list discussions on dev@.

Note:
All votes, releases, and policy decisions must be made on the mailing list so that they’re properly recorded and archived.

Examples in Practice

Summary and Core Principles

Mentor Guidance

Mentors should regularly check that:

• Key discussions and votes occur on dev@.
• Off-list or private discussions are summarized publicly.
• Meeting notes and GitHub threads are mirrored on the list.
• The podling consistently uses mailing lists before graduation.

Alignment with ASF Policy

This guidance supports ASF-wide communication practices:

• ASF Community Development: promotes open, archived, inclusive communication.
• ASF Infrastructure: supports GitHub–mailing list integration for transparency.
• Incubator Policy: requires podlings to demonstrate public discussion and decision-making before graduation.
• ASF Maturity Model: identifies openness and communication as key measures of community health.

It adds practical examples for using newer collaboration tools responsibly while preserving ASF’s open, asynchronous model.

Further Reading

• ASF Community Development: Project Communications
• The Apache Way
• Incubator Policy
• ASF Maturity Model