Hitchhiker's Guide — Apache Contribution Mechanics

(0) 30-Second Mental Model

Patch review           Semantic versioning         Issue lifecycle
─────────────          ───────────────────         ───────────────
diff --git a/X b/X     1 . 2 . 3 - alpha.1         OPEN
@@ -10,4 +10,6 @@     │   │   │   └── pre-release     ↓
 context               │   │   └─── patch (bug fix)  IN_PROGRESS
+addition              │   └─────── minor (additive) ↓
-removal               └─────────── major (breaking) IN_REVIEW
 context                                               ↓
                       1.2.4 > 1.2.3                RESOLVED
reviewer asks:         2.0.0 > 1.9.9 (breaking!)     ↓
"where is the test?"   1.2.3-rc.1 < 1.2.3            CLOSED

(1) Unified Diff Format

A git format-patch email or GitHub diff is a unified diff. Every Apache review thread references this format.

diff --git a/src/main/java/Foo.java b/src/main/java/Foo.java   ← file header
index abc1234..def5678 100644
--- a/src/main/java/Foo.java
+++ b/src/main/java/Foo.java
@@ -10,7 +10,8 @@ public class Foo {                              ← hunk header
 public class Foo {                                             ← context (space)
-    return "hello";                                           ← deletion (-)
+    return "Hello, World!";                                   ← insertion (+)
+    // new comment                                            ← insertion (+)
 }

Parsing rules:

• diff --git a/X b/Y → new file starts; Y is the new path
• @@ -old_start,old_count +new_start,new_count @@ → hunk header; not counted
• Lines starting with + (not +++) → insertions
• Lines starting with - (not ---) → deletions
• Lines starting with → context (unchanged)

Test coverage signal: Apache reviewers expect a test file for every production change. A patch that only modifies src/main/java/ with no change to src/test/java/ is a red flag.

(2) Semantic Versioning 2.0.0

Apache project releases follow SemVer:

MAJOR . MINOR . PATCH [-pre-release] [+build-metadata]

Precedence Rules

1. Compare MAJOR, then MINOR, then PATCH numerically.
2. A release version (1.2.3) has higher precedence than the same version with a pre-release label (1.2.3-rc.1).
3. Pre-release identifiers (dot-separated) are compared left-to-right:
   • Both numeric → compare as integers (9 < 10)
   • Numeric vs alphanumeric → numeric is lower (1 < alpha)
   • Both alphanumeric → lexicographic ASCII order
4. Shorter tuple is lower when all common identifiers are equal (1.0.0-alpha < 1.0.0-alpha.1).
5. Build metadata (+build.1) is ignored for comparison.

Classic ordering example

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta
           < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11
           < 1.0.0-rc.1 < 1.0.0

(3) Apache JIRA Issue Lifecycle

Apache projects use JIRA for all issue tracking. The canonical state machine:

          OPEN ──────────────────────────────┐
           │                                 │
           ▼                                 │ (quick close)
       IN_PROGRESS ◄────────────────────┐    │
           │                            │    │
           ▼                       (needs work)
       IN_REVIEW ──────────────────────┘    │
           │                                 │
           ▼                                 ▼
        RESOLVED ◄───────────────────────────┘
        │       │
        ▼       ▼
     CLOSED  REOPENED ──► IN_PROGRESS

Key transition rules:

• IN_REVIEW → IN_PROGRESS — reviewer requested changes; author needs to rework
• RESOLVED → REOPENED — regression found after closing; happens at release time
• CLOSED → REOPENED — re-opened from a fully closed issue; requires a comment
• No transition from CLOSED directly to IN_PROGRESS — must go through REOPENED

Fix version field — committers set fixVersion when resolving. This is how the release manager knows what to include in the release notes.

(4) What Apache Reviewers Actually Check

When reviewing a patch for an Apache project, committers check:

(5) Interview Q&As

(6) References

• Unified diff format — GNU diffutils manual
• Semantic Versioning 2.0.0
• Apache JIRA
• How to Contribute to Apache Spark
• Apache Release Policy