This guide explains how the Apache Incubator develops shared understanding over time, and why judgment, context, and experience play a central role in Incubator decision-making.
This guide is intended for:
It is particularly relevant for people new to Incubator roles who are looking for clarity on how guidance, precedent, and judgment interact.
This guide describes how the Incubator:
It focuses on Incubator review work (proposals, reports, releases, graduation) and the mentoring and oversight discussions that surround it. It complements, but does not replace, ASF policy and legal guidance. Where this guide describes practice or experience, it must not be read as modifying or overriding formal ASF or Incubator policy.
The Incubator does not operate as a checklist-driven or purely rules-based system. While policies establish boundaries, most Incubator decisions require interpretation based on context:
Rules and documented expectations help as shortcuts to accumulated experience, but they are applied with judgment rather than enforced mechanically.
Many concerns only become clear when viewed in context. Timing, responsiveness to feedback, and vendor dynamics can significantly change how the same surface-level issue should be interpreted.
The goal is consistency of reasoning, not identical outcomes. Reviewers are encouraged to explain concerns in terms of observable behaviour and policy boundaries so that the reasoning can be challenged, refined, or disagreed with in public.
Most learning in the Incubator begins with practical review work, including:
Issues often surface indirectly, through wording, omissions, tone, or patterns of activity, rather than as explicit problems. These discussions are the Incubator’s main input signal: they reveal what projects do, not just what they claim.
Learning depends on transparency. Decisions, concerns, and reasoning are expected to be discussed on public mailing lists, with summaries provided when side channels are used so that the experience can be shared and revisited.
When an issue first arises, it is usually handled as a case-specific discussion.
As similar issues recur:
Only when patterns persist does the Incubator typically invest in formalising guidance for broader use.
The reappearance of familiar issues does not necessarily mean that guidance has failed.
Some topics recur because:
In these cases, rules and documented expectations can serve as useful shortcuts, helping reviewers and projects avoid re-learning the same lessons.
However, repetition also persists because similar surface-level issues can arise in different contexts and require different responses. Guidance reduces effort and confusion, but judgment is still required to interpret and apply it appropriately.
Most Incubator learning remains guidance rather than policy.
The Incubator typically formalises rules only when:
Even then, policies usually define boundaries, while practice guides explain how to operate within them.
Field Guides capture patterns that have appeared often enough to be useful to others.
They are intended to:
They are not a policy substitute, and they are not intended to be used as a checklist for approval.
Incubator guidance is most effective when used to inform discussion rather than to conclude it.
Reviewers are encouraged to:
If a situation seems to call for a strict yes-or-no answer, it is often worth revisiting the underlying question.
Prior cases help explain reasoning, but they are not binding. Outcomes are reached through current consensus, not by applying precedent mechanically or treating it as authoritative.
Concerns often begin with mentor feedback and are addressed through public discussion.
Escalation typically occurs when:
The goal of escalation is almost always correction and learning, not punishment. Projects are encouraged to request clarification, propose mitigations, and cite evidence in public discussions. Disagreement is expected to be handled through transparent reasoning and consensus.
Learning in the Incubator is continuous.
Experience from new cases feeds back into:
This feedback loop depends on open discussion, willingness to revisit assumptions, and acceptance that guidance will evolve over time.
For mentors and IPMC members, this means:
For podlings and proposers, it means:
The Incubator learns in public by discussing real cases, forming shared expectations, and documenting patterns when doing so helps others. Documentation provides shortcuts, but judgment and context remain essential to sustaining healthy Apache communities.