Apache Project Reporting Guide

1. Introduction

1.1 Purpose of This Guide

This guide is for Project Management Committee (PMC) Chairs and members of Apache Top-Level Projects (TLPs). It explains the purpose of board reports, how to write them effectively, and how they fit into the ASF’s oversight and governance model.

For the official ASF policy and reporting instructions, see: 👉 ASF Board Reporting Guide

2. Why Reports Matter

Board reports are the primary way the ASF Board of Directors oversees project health. They:

  • Fulfill the ASF’s legal and fiduciary duties as a 501(c)(3).
  • Help identify risks early, so the ASF can provide support and guidance.
  • Promote transparency and trust across the ASF community.
  • Serve as the project’s public status update, archived in board minutes.

3. Audience for Reports

Your report is read by:

  • ASF Board of Directors – for oversight and governance.
  • ASF Officers – such as the President and Vice Presidents, with related duties.
  • ASF Members – reports are published in the board minutes.
  • Wider ASF community – board minutes are public, and reports reflect on the health and professionalism of your project.

4. Reporting Requirements

  • Reports are submitted quarterly, but each project is assigned a specific month within the quarter.
  • The reporting schedule is maintained in the Board Agenda Tool.
  • Reports are sent to board@apache.org or submitted via ASF tooling.
  • Reports are strongly encouraged one week before the meeting to give Directors time to review.
  • The PMC Chair is responsible for submitting the report, but the entire PMC should help draft and review it.

👉 See the official ASF Board Reporting page for more details.

4a. Incubator Reports

Incubating projects (“podlings”) follow a different reporting process than TLPs, because they are still under the guidance of the Apache Incubator PMC (IPMC). Please see the Incubator Reporting Guide for differences.

5. Submitting Your Report

Most projects use the Board Agenda Tool:

  • Log in with your ASF ID.
  • Navigate to the current agenda.
  • Add or edit your project’s report in the correct section.
  • The tool provides a report template and auto-fills some project data.

Alternatively, reports can be emailed directly to board@apache.org.

6. Writing Effective Reports

6.1 Characteristics of a Good Report

A good report is:

  • Clear, factual, and concise.
  • Focused on changes since the last report.
  • Includes data such as membership changes and releases.
  • Reflects community diversity and activity.
  • Honest about challenges as well as successes.
  • Highlights progress and achievements.

Short Good Example

“Since last report, 2 new committers joined. Released 1.2.0 in July. Mailing list traffic steady (~150 msgs). PMC diversity increasing with contributors from 3 companies. Considering a new committer nomination next month.”

6.2 Characteristics of a Poor Report

A poor report:

  • Is missing or consistently late.
  • Uses boilerplate text with no updates.
  • Is too vague, e.g., “Community is fine” without details.
  • Omits known problems or disputes.
  • Can be overly long, obscuring the key points.
  • Focuses only on technology, ignoring community health.

Short Poor Example

“Project is fine. We released. No issues.”

6.3 Full Good Report Example

Below is a complete sample report in the style the ASF Board expects. Actual reports will vary, but they should generally cover these sections in a few short paragraphs.

Apache DataFlow Board Report

Description

Apache DataFlow provides tools and libraries for scalable data processing, designed to integrate with a variety of data storage and analytics systems.

Project Status

The project remains active and stable, with steady releases and community contributions. The focus this quarter has been on improving cloud integration features and preparing for a minor version release. No significant issues are blocking progress.

Membership Data

  • PMC size: 11 (unchanged since last report)
  • PMC changes since last report:
    • Added: (none)
    • Retired: (none)
  • Committer changes since last report:
    • Added: Alice Kim (2025-07-02), Carlos Álvarez (2025-07-19)
    • Retired: (none)

Community Changes

  • dev@ traffic was ~180 msgs in June, ~220 in July, and ~150 in August. This level is consistent with the past quarter and reflects steady project discussions, primarily around release planning and feature proposals.
  • GitHub activity included 95 pull requests merged and 60 issues resolved this quarter, which is typical for the project. Reviews are broadly shared across contributors, not concentrated on one or two individuals.
  • Contributors come from at least 3 organizations, with no single company dominating activity.
  • Two new contributors submitted first patches in August, both of which were reviewed and merged promptly, showing that the onboarding new contributors is functioning well.

Releases

  • 2.5.1 (2025-07) — maintenance release with bug fixes and minor improvements.

Community Health

The community remains healthy, with consistent engagement on mailing lists and GitHub. Reviews are generally prompt (median ~5 days to merge). Contributor activity is balanced across organizations; longer-term, increasing PMC diversity remains a goal.

Issues for the Board

None at this time.

6.4 Full Poor Report Example

This example shows what an unhelpful report might look like.

Apache DataFlow Board Report

Description

Apache DataFlow provides tools and libraries for scalable data processing, designed to integrate with a variety of data storage and analytics systems.

Project Status

Everything is fine.

Membership Data

  • PMC size: 11
  • Committers: 32

Community Changes

  • Mailing lists: 180 msgs in June, 220 in July, 50 in August.
  • GitHub: 95 PRs merged, 60 issues resolved.

Releases

We did a release recently and are working on another.

Community Health

The community is healthy.

Issues for the Board

None.

6.5 Key Lessons from the Examples

  • Good reports provide context: they don’t just give numbers, they explain what the numbers mean.
  • Poor reports rely on vague phrases (“Everything is fine”) or list raw statistics without interpretation.
  • Good reports include names and dates for committer and PMC changes.
  • Poor reports leave out essential details (release versions, specific challenges, diversity of activity).
  • A real board report is usually a few short sections totalling several paragraphs, not just a sentence or two.

7. Common Pitfalls

  • Late reports reduce effective oversight.
  • Vague or minimal reports make project health unclear.
  • Boilerplate text with no real updates.
  • Known issues not mentioned.
  • Reports that are too long and bury the key facts.

8. Self-Checks for Project Health

Use this as a quarterly checklist when preparing your report. If you see any of these issues, mention them in your report so there’s transparency. Not all of them require Board intervention.

  • Declining activity or stalled discussions
  • Decisions happening off-list
  • Over-reliance on one company or individual
  • Repeated release or IP issues

9. Consequences of Missing Reports

The Board or Shepards will chase late reports. If a project fails to report:

  • The project will be asked to report again the following month.
  • Persistent failures may trigger a roll call to confirm at least 3 active PMC members.
  • In extreme cases, the Board may replace the Chair or PMC members.
  • If oversight consistently fails, Attic discussions may begin.

The goal is always to restore effective oversight, not to punish.

10. Public Nature of Reports

Board reports are public documents. They appear in the ASF board minutes and are visible to Members and the wider community. Reports reflect directly on your project’s:

  • Health
  • Professionalism
  • Transparency

11. When to Raise Issues to the Board

Some issues are serious enough that the Board expects to be notified, even if you think the PMC can resolve them. Always include these in your report:

  • PMC Chair planning to step down
  • Fewer than 3 active PMC members
  • Difficulty finding or mentoring new contributors
  • Trademark or branding disputes
  • Serious community conflicts that cannot be resolved within the PMC
  • Oversight gaps beyond the PMC’s ability to manage

It is better to raise potential risks early than to under-report.

12. How the Board Uses Reports

  • No response usually means “all good.”
  • The Board generally comments only if clarification is needed.
  • The Board follows up when issues are raised.
  • Reports form a long-term record of project health and governance.

13. Good Practices

  • Keep a rolling draft, updated monthly.
  • Share drafts on dev@ for transparency and feedback.
  • Be honest, the ASF helps projects, it does not punish them.
  • Highlight successes, not just challenges.
  • Use ASF templates and board agenda tools to simplify reporting.

14. Support and Resources

15. Checklist Before You Submit

  • Have you included membership changes?
  • Did you list recent releases?
  • Did you cover community health as well as technology?
  • Did you highlight both successes and challenges?
  • Is the report concise, factual, on time, and ready for public view?

16. FAQ

Q: What if my report is late?

A: Submit as soon as possible. The Board may ask you to report again the following month. Persistent delays could trigger a roll call.


Q: How much detail should I include?

A: Enough that someone unfamiliar with the project understands its current health and progress. Concise summaries with clear examples are best.


Q: Do I need to include every GitHub statistic?

A: No. Metrics are useful if they show trends, but context is more important than raw numbers.


Q: Who can help me draft or review reports?

A: Any PMC member can contribute. Many projects prepare drafts so the community can review.


Q: What happens if my project has fewer than 3 active PMC members?

A: This is a governance risk. Report it to the Board so it can help resolve the issue.


Q: What should I do if my project is struggling with community issues?

A: Raise the concern in your report and, if needed, contact the ASF Board or Officers for support.


17. Key Takeaway

Board reports are a project health check. They show the ASF and the wider community that your project is thriving, stable, and transparent.

  • No labels