• Created by Unknown User (jmclean), last updated on Dec 27, 2025 4 minute read

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.

Who This Guide Is For

This guide is intended for:

  • Incubator mentors
  • IPMC members
  • Podling PPMCs

It is particularly relevant for people new to Incubator roles who are looking for clarity on how guidance, precedent, and judgment interact.

Purpose

This guide describes how the Incubator:

  • recognises recurring issues,
  • develops shared understanding,
  • decides when to document guidance,
  • and applies judgment when guidance does not neatly fit a situation.

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.

1. Applying Rules with Judgment

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:

  • stage of incubation,
  • community structure,
  • mentor engagement,
  • and observed behaviour over time.

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.

2. How Issues Surface

Most learning in the Incubator begins with practical review work, including:

  • proposal discussion threads,
  • podling status reports,
  • release votes and announcement reviews,
  • graduation discussions,
  • mentor questions or escalations.

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.

3. From Individual Cases to Shared Understanding

When an issue first arises, it is usually handled as a case-specific discussion.

As similar issues recur:

  • informal shared memory develops among reviewers,
  • common questions and expectations begin to stabilise,
  • experienced participants recognise patterns more quickly.

Only when patterns persist does the Incubator typically invest in formalising guidance for broader use.

4. Why Repetition Is Not Always a Failure

The reappearance of familiar issues does not necessarily mean that guidance has failed.

Some topics recur because:

  • they reflect structural risks that appear across many projects, or
  • they represent common pitfalls that benefit from clear, repeatable guidance.

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.

5. When Guidance Becomes Policy

Most Incubator learning remains guidance rather than policy.

The Incubator typically formalises rules only when:

  • the risk is repeatable and high-impact,
  • consistency matters across all projects,
  • and judgment alone is not a reliable safeguard.

Even then, policies usually define boundaries, while practice guides explain how to operate within them.

6. The Role of Field Guides

Field Guides capture patterns that have appeared often enough to be useful to others.

They are intended to:

  • shorten review cycles,
  • reduce repeated explanation,
  • provide shared language for discussion,
  • act as practical shortcuts to accumulated experience.

They are not a policy substitute, and they are not intended to be used as a checklist for approval.

How to Use This Guidance

Incubator guidance is most effective when used to inform discussion rather than to conclude it.

Reviewers are encouraged to:

  • reference guidance to explain concerns,
  • adapt expectations to context,
  • and make their reasoning explicit.

If a situation seems to call for a strict yes-or-no answer, it is often worth revisiting the underlying question.

7. A Note on Precedent

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.

8. How Concerns Escalate

Concerns often begin with mentor feedback and are addressed through public discussion.

Escalation typically occurs when:

  • concerns are repeatedly raised without response,
  • there is risk to ASF marks, infrastructure, or reputation,
  • governance or neutrality expectations are not being met,
  • or there is a persistent gap between stated practice and observable behaviour.

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.

9. The Feedback Loop

Learning in the Incubator is continuous.

Experience from new cases feeds back into:

  • shared expectations,
  • mentor practice,
  • and, where appropriate, updated guidance.

This feedback loop depends on open discussion, willingness to revisit assumptions, and acceptance that guidance will evolve over time.

10. What This Means for Participants

For mentors and IPMC members, this means:

  • applying experience with care,
  • explaining reasoning rather than citing rules alone,
  • and helping projects understand why issues matter.

For podlings and proposers, it means:

  • engaging with feedback in good faith,
  • recognising that similar issues may be treated differently in different contexts,
  • and understanding that guidance supports learning and shared expectations.

11. Conclusion

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.

  • No labels