Level 2: Apache Contributor Onboarding

Level 1 gave you a Tez you can build, test, and run a DAG on. This level turns that capability into merged code. You will learn how Apache Tez is actually contributed to today — which is not the JIRA-plus-.patch-file folklore that most "Apache workflow" write-ups still describe. Modern Tez is a GitHub pull-request project that keeps JIRA as its issue tracker: you file (or find) a TEZ-XXXX issue on issues.apache.org, open a PR on github.com/apache/tez whose title is the JIRA key, and a committer squash-merges it after Yetus precommit goes green and a human reviews it.

This is deliberately a workflow level. The changes are surgical — a Javadoc fix, an input validation guard, a missing test. Nothing here will surprise a reviewer. That is the point: you drill the mechanics now, against the real repository, so that Levels 3–9 can be about the engine.

Ground truth. Everything in this level is checked against a current apache/tez checkout: the root pom.xml module list, .asf.yaml, .github/workflows/build.yml, the Jenkinsfile, dev-support/tez-personality.sh, and git log. Where this page says "run this," run it against your own clone and trust its output over any text — the code moves between branches.

Learning Objectives

By the end of Level 2 you must be able to:

1. Describe the real Tez contribution model end-to-end: JIRA issue → fork → branch → commit (TEZ-XXXX: …) → GitHub PR → GitHub Actions + Jenkins/Yetus precommit → review → squash-merge.
2. Navigate every top-level module in the root pom.xml and say what each is for and what it depends on.
3. Create an Apache JIRA account, find a Minor/Trivial unassigned issue, and comment on it without stepping on another contributor.
4. Write a commit and PR title in the enforced TEZ-XXXX: Description form (verified against git log).
5. Run the same gates precommit runs — spotless, checkstyle, apache-rat, spotbugs, and the scoped unit tests — locally, so CI is green on the first push.
6. Read a Yetus/GitHub Actions failure and map each check back to the local command that reproduces it.
7. Review a PR the way a committer does: correctness, test coverage, compatibility, style, diagnostics.

The Modern Tez Contribution Model

Apache projects vary widely in mechanics. Do not assume the "email a patch to the list" model — Tez does not work that way anymore. Read .asf.yaml in the repo root and you can see the current setup encoded directly:

sed -n '/^github:/,/^notifications:/p' .asf.yaml

The load-bearing lines:

So the pieces you must internalize:

There is no .github/pull_request_template.md in the repo — confirm with ls .github (you will see only workflows/). Tez does not auto-populate a PR checklist, which means the discipline is on you: a clear title, a description of the problem and fix, a note of how you tested, and a link to the JIRA. Governance context — the PMC, meritocracy, how committership is earned — is covered in committer-mindset and pmc-responsibilities; for contribution mechanics, this page is enough.

JIRA still matters

The JIRA key is the spine of the whole flow. It names your branch, prefixes your commit, titles your PR, and (via jira_options: link) gets back-linked from the PR automatically. File issues and read existing ones as covered in jira-review and design-via-jira.

The PR Lifecycle

flowchart TD
    A["Find or file a TEZ-XXXX JIRA issue"] --> B["Comment: 'I'm looking into this'"]
    B --> C["Fork apache/tez; clone; add upstream remote"]
    C --> D["git checkout -b TEZ-XXXX from up-to-date master"]
    D --> E["Make the surgical change (+ test)"]
    E --> F["mvn spotless:apply"]
    F --> G["Local gates: checkstyle, apache-rat, spotbugs, scoped tests"]
    G --> H["git commit -m 'TEZ-XXXX: Description'"]
    H --> I["git push origin TEZ-XXXX; open PR against master"]
    I --> J["GitHub Actions build matrix + Jenkins/Yetus precommit"]
    J -->|red| G
    J -->|green| K["Committer review"]
    K -->|changes requested| E
    K -->|approved| L["Committer squash-merges to master"]
    L --> M["JIRA moved to Resolved/Fixed, fixVersion set"]

The state machine in words:

1. Claim. Find a Minor/Trivial, unassigned issue with no open PR, and comment before you start. Etiquette is in community-interaction.
2. Fork and branch from an up-to-date master. Branch name is conventionally the JIRA key (TEZ-XXXX) — you will see this exact convention in the merged history.
3. Change exactly what the issue asks — plus a test. Scope creep is the #1 reason first PRs stall.
4. Format and gate locally. mvn spotless:apply first (it fixes import order, trailing whitespace, license headers, and the final newline automatically), then the checks below.
5. Commit with a TEZ-XXXX: Description subject. You do not need to squash your own commits — the committer squashes at merge — but keep them coherent.
6. Push and open a PR against master. Title it TEZ-XXXX: Description; write a body even though no template forces you to.
7. CI. GitHub Actions compiles across a Java 21/25 × Ubuntu/macOS matrix; Jenkins runs Yetus, which posts a per-check comment (with emoji votes) on the PR.
8. Review and merge. Address every comment with new commits. A committer squash-merges once green and approved, and moves the JIRA to Resolved.

The CI checks you will see

Two systems run. Map each to the local command that reproduces it:

Running spotless:apply + checkstyle:check + the scoped tests before you push is the single biggest lever on review speed. Quality expectations are in patch-quality.

Source Areas to Inspect

You do not need to read these end-to-end; you need to know they exist and what they govern.

Apache Tez JIRA Structure

Issues are typed and prioritised. As a Level 2 contributor you work only the bottom of the priority table.

For Level 2: work only Minor and Trivial issues until you have at least three accepted PRs. Do not pick up Major+ work yet — you will get it wrong in ways that burn reviewer trust.

Components point you at a module: Tez (core/DAG), Tez UI, Test, and area labels that map onto the modules in Lab 2.1. Browse recent issues with project = TEZ ORDER BY updated DESC to see what active work actually looks like.

Deliverables

Demonstrate all of the following before advancing to Level 3:

• An Apache JIRA account, and one Minor/Trivial issue you have studied and commented on.
• A fork of apache/tez with an upstream remote and a TEZ-XXXX topic branch off an up-to-date master (Lab 2.1, Lab 2.2).
• A module map you built yourself from the root pom.xml, with each module's role and its inter-module dependencies (Lab 2.1).
• A clean local mvn spotless:check, mvn checkstyle:check, and mvn apache-rat:check on your change.
• A commit whose subject is TEZ-XXXX: Description, matching the form in git log.
• A walked bug fix with a reproducing unit test in the TestTezIds style (Lab 2.3).
• A completed review of the flawed example patch — you found every flaw a committer would flag (Lab 2.4).

Common Mistakes

How to Verify Success

# Your branch is clean relative to master and contains only intended changes
git fetch upstream
git diff upstream/master --stat        # only the files you meant to touch

# The full local gate, on the module you changed
mvn spotless:check       -pl <module>
mvn checkstyle:check     -pl <module>
mvn apache-rat:check     -pl <module>
mvn test                 -pl <module> -am -Dtest=<RelevantTestClass>

# Your commit subject matches the enforced form
git log -1 --pretty=%s   # -> TEZ-XXXX: Description

PR Profile: Level 2 Graduate

A Level 2 graduate can credibly open these PRs end-to-end, with green CI on the first or second push:

You are not yet ready to submit changes to the state machines, the shuffle path, the AM scheduling, or the wire/protobuf formats — those are Levels 3–9. What you are ready for is the thing most contributors get wrong: a clean, focused, tested, correctly-titled PR that a committer can squash-merge without a five-round back-and-forth.

Next: Lab 2.1 — Navigate the Tez Repository Structure.