Hitchhiker's Guide: Phase 12 — Final Apprenticeship Milestone

The capstone phase. Everything before this trained components: navigation, review, release mechanics, performance, governance. This phase assembles them into the three artifacts that are a committer's working life — a complete contribution, a design document, and the transfer of what you learned to the next person.

Table of Contents

Section 1: The Full Contribution Cycle

A real ASF contribution touches eight distinct artifacts, and committers judge all eight:

  1. The issue — problem statement with reproduction. A good JIRA is falsifiable: someone else can confirm the bug exists and confirm your fix removes it.
  2. The patch — minimal diff that fixes the issue and nothing else. Scope creep is the #1 first-patch killer: every extra refactor multiplies review cost.
  3. The tests — one that fails without the patch (proves you fixed the right thing) plus edge cases. A patch whose test passes on unpatched code tests nothing.
  4. Commit message — PROJECT-1234: <what changed and why> with body explaining the approach and alternatives rejected. git log is the project's long-term memory.
  5. Review responses — Section 3.
  6. The release note — Section 4.
  7. Backport decisions — does this go to maintenance branches? Bug fixes usually yes, behavior changes usually no; you must state your recommendation, not leave it implicit.
  8. Follow-through — watching CI after merge, responding if it breaks something. The merge is the midpoint of the contribution, not the end.

Lab 01's StringNormalizer exercise is deliberately small so that the cycle is the content — the same eight artifacts at one-day scale.

Section 2: The Design Document

The design doc is the unit of technical leadership in distributed open-source work — it is how you change a system you don't control. The load-bearing sections:

  • Problem statement: measurable and agreed-upon before solutions appear. If the problem statement is contested, no design will get consensus; settle it first on the list.
  • Goals / Non-goals: non-goals are the more important half — they pre-empt scope arguments and record what you chose not to solve.
  • Alternatives considered: 2–3 real designs with honest costs, including "do nothing." Reviewers trust documents that argue against their proposal competently. An alternatives section containing one straw man is a tell.
  • Compatibility analysis: what breaks, for whom, at which boundary (source/binary/ behavioral/wire — the Phase 10/11 taxonomy). For ASF projects this section decides votes.
  • Rollout & revert: how it ships behind what flag, what the metrics of success are, and — the part people omit — how it is undone if wrong.
  • Open questions: explicitly listed. Pretending certainty you don't have reads as inexperience to senior reviewers; a sharp open-questions list reads as judgment.

Length discipline: if the doc exceeds ~6 pages, the design is probably not decomposed enough. Big designs ship as a sequence of small consensuses (cf. Kafka KIPs, Spark SPIPs).

Section 3: Responding to Review — the Decisive Skill

PMC members repeatedly say the same thing: they vote committership on how candidates respond to review, because it predicts decade-scale collaboration. The mechanics:

  • Respond to every comment — fixed / pushed back with reasons / question. Silence on a comment reads as either sloppiness or stonewalling.
  • Batch your pushes: one revision addressing all comments, not a commit per comment; reviewers re-review whole revisions.
  • Distinguish the three comment types and answer each in kind: blocking technical objections (resolve or rebut with evidence), preferences (usually just take them — spend disagreement budget on things that matter), and questions (often a sign your code needs a comment or doc — fix the artifact, not just the thread).
  • When you disagree: restate their concern accurately first (proves you understood), then evidence. "You're right that X; however the benchmark in comment 3 shows Y" lands; "no, because" doesn't.
  • When you were wrong: say so fast and visibly, then convert your misunderstanding into a code comment or test so the next person doesn't repeat it. (This is Scenario 5 in interview-prep/04-code-review-scenarios.md.)

Lab 01's REVIEWER_RESPONSE.md is graded against exactly this list.

Section 4: Release Notes That Earn Their Place

A release note is written for someone upgrading under time pressure who will read one sentence. Format that works:

PROJECT-1234 — normalize() now trims Unicode whitespace (was: ASCII only). Who is affected: callers relying on non-ASCII whitespace surviving normalization. Action: none for most users; set legacy.normalize=true to restore old behavior (removed in 4.0).

Rules: lead with observable behavior change, not implementation; name the affected audience explicitly; always state the action (including "none"); link the migration path if any. If you cannot write the "who is affected" line, you don't understand your own change's blast radius yet — go back and find out.

Section 5: Reflection as an Engineering Artifact

The "What I Wish I Knew" document (Lab 03) is not a diary — it is transfer of calibration. What makes one useful to the next contributor:

  • Specific costly surprises with their detection signature ("a silent CI label means X, here's how to tell").
  • Re-ranked priorities: what you over-invested in early vs what actually built trust — almost everyone reports under-investing in reviewing others and over-investing in writing more code.
  • Honest failure inventory with what each cost and what guard now exists.
  • Advice that is falsifiable rather than platitudes ("respond to review within 48h even if just 'looking this week' — silence decays reviewer attention" beats "communicate well").

This genre is real in the ASF world: incoming committers are routinely pointed at exactly such documents.

Lab Walkthrough Guidance

Order: Lab 01 → Lab 02 → Lab 03 (reflection last, with the experience fresh).

  • Lab 01: run mvn test first; read the existing StringNormalizer and its tests as a reviewer would before touching anything. Then execute the eight-artifact cycle. Grade yourself against Section 1; the REVIEWER_RESPONSE.md against Section 3.
  • Lab 02: pick a design problem from Phases 10–11 (scheduler improvement, metastore scaling, API evolution — the system-design/ walkthroughs show the target altitude). Write to the Section 2 skeleton; have someone (or a later re-read after a week) attack the alternatives section.
  • Lab 03: write against Section 5's anti-platitude rules.

Success criteria — you are done when: your Lab 01 package could be posted to a real ASF project without embarrassment; your design doc's alternatives section would survive a hostile reviewer; your reflection contains at least three things you genuinely did not know at Phase 01 with their costs attached.

Interview Q&A

Q: Walk me through a contribution end-to-end. Where do contributions actually fail? Strong answer enumerates the cycle (Section 1) and locates the real failure points: scope creep at the patch stage, tests that don't fail without the fix, silence during review, and abandonment after the first round of feedback — not the code itself.

Q: How do you structure a design doc for a distributed system change? Problem (agreed first) → goals/non-goals → alternatives with honest costs → compatibility across all four dimensions → rollout and revert → open questions. Emphasize non-goals and revert: those are the sections that distinguish staff-level docs.

Q: A reviewer's blocking comment is wrong. What do you do? Restate their concern to prove comprehension; bring evidence (test, benchmark, spec citation); if they hold, take it to the list rather than grinding in the PR; and accept that on a justified technical veto, consensus — not being right — ships code.

Q: What do you wish you'd known before your first contribution? Have a real answer from your Lab 03. The generic shape that rings true: trust accrues from reviewing and follow-through more than from code volume; small patches compound; the mailing list is the project.

References