Design via JIRA, Not PRs

Apache projects design in the open. In Tez, "the open" is the TEZ JIRA project and the dev@tez.apache.org mailing list — not the GitHub PR.

A PR with a "see what you think" attitude and no JIRA attached will be ignored. A JIRA with a clear problem statement and rough design will get responses within days, often from people who never read the PR. This chapter is about why, and how to use that system.

Why Not Just PRs?

GitHub PRs at Apache are mirrors of patches. They are convenient for diff viewing, but they are not the system of record. The system of record is:

If a discussion happens only on a PR and the PR is later force-closed or the repo moves, the rationale evaporates. JIRA + mailing list don't move.

Concrete consequence: when you read code in tez-dag/ and ask "why?", the answer is almost certainly in a JIRA referenced from the commit message — see Reading the Codebase, Strategy 3.

The TEZ JIRA Workflow

A Tez JIRA moves through these statuses:

Open → In Progress → Patch Available → Resolved → Closed
                                    ↘ Reopened

Triggers:

You only set "Patch Available" yourself. Everything else above the dotted line is yours; everything below requires a committer.

Reading Old JIRAs for Context

The single highest-leverage Tez skill is reading old JIRAs. Conventions:

• Issues are referenced as TEZ-NNNN in commit messages and source comments. You will see // see TEZ-3045 or // TEZ-1597 peppered through the code.
• Search them at https://issues.apache.org/jira/browse/TEZ-NNNN.
• The "Activity" tab shows the design conversation. The "Attachments" tab shows the patch iterations (TEZ-NNNN.001.patch, TEZ-NNNN.002.patch, ...).

Try this now:

cd ~/tez-src
git log --all --oneline | grep -oE "TEZ-[0-9]+" | sort -u | tail -20

Pick one and open it in a browser. Read the description, the comments, and the patch iterations. You will see the design happen — alternative considered, rejected, refined. This is more useful than any architecture document because it shows reasoning, not conclusions.

When to Open a JIRA Yourself

You open a JIRA before writing the patch when any of the following is true:

You do not need a JIRA to:

• Ask a question on dev@ or user@
• File a documentation question
• Patch a private fork

The JIRA Description Skeleton

A Tez JIRA description that committers can act on contains, in order:

## Problem

(Two to four sentences. What is wrong. Who hits it.)

## Reproduction

(Steps to reproduce, or a code sample. If a test reproduces it, name the test class.)

## Root Cause

(One paragraph. Cite file and method.)

## Proposed Fix

(One paragraph. What you intend to do. Mention any alternatives considered.)

## Compatibility

(One sentence. Wire compat? API change? Config rename? "None." is a valid answer.)

## Test Plan

(One paragraph. Which tests pass after the change. Any new test added.)

A trivial bug fix may collapse Compatibility and Test Plan to one line each. A new API must expand them.

Design Doc on a JIRA — Skeleton

For anything larger than a single-file fix, attach a design doc (Markdown or PDF) to the JIRA. The skeleton:

# TEZ-NNNN: <short title>

## 1. Problem
What is wrong today. Who is affected. Why "do nothing" is not acceptable.

## 2. Goals
Bulleted, testable. "DAGPlan submission survives a 10 MB plan without OOM."

## 3. Non-Goals
What this design explicitly will not address. Prevents scope creep.

## 4. Alternatives Considered
- Option A: <description>. Pros / Cons. Why rejected.
- Option B: <description>. Pros / Cons. Why rejected.
- Option C (chosen): <description>. Pros / Cons.

## 5. Chosen Approach
Architecture sketch. Mermaid or ASCII. Cite files that will change.

## 6. Compatibility
- Wire compat: <change to any proto? backward compatible?>
- API compat: <InterfaceAudience.Public touched? deprecation plan?>
- Config compat: <new keys? renamed keys? default change?>

## 7. Test Plan
- Unit tests: which classes
- Integration: MiniTezCluster scenarios
- Manual: any out-of-suite verification

## 8. Rollout
- Default off? On? Feature flag name?
- Migration steps for existing users.

Attach as TEZ-NNNN-design.md or TEZ-NNNN-design.pdf. Announce it on dev@ with subject [DISCUSS] TEZ-NNNN: <short title> and a link.

Expect 1–2 weeks of asynchronous discussion before consensus. Do not start patching until the design is at least loosely agreed — patches without design buy-in get rejected.

"See TEZ-NNNN" — The Codebase Convention

Search the Tez source for back-references:

cd ~/tez-src
grep -rn "TEZ-[0-9]" tez-dag/src/main/java | head -20

Every such reference is a permanent link from the code to a design conversation. When you add a non-obvious workaround, you do the same — leave a // TEZ-NNNN: <one line why> so the next reader can find your reasoning.

When the Design Lives on dev@ Only

Some discussions never reach JIRA — release planning, branch policy, build infrastructure. Those live on dev@tez.apache.org only. Archive:

• https://lists.apache.org/list.html?dev@tez.apache.org

Search by subject prefix:

Subscribing: send empty mail to dev-subscribe@tez.apache.org.

Validation Artifacts

After this chapter you should be able to produce:

1. The URL of three different TEZ-NNNN JIRAs cited from the Tez source, and a one-line summary of what each one is about.
2. A draft JIRA description (in a local file ~/tez-notes/draft-jira.md) for a bug or improvement you have noticed, following the skeleton above.
3. A subscription confirmation to dev@tez.apache.org.
4. One archived [DISCUSS] thread URL relevant to a Tez area you care about.

The next chapter — Community Interaction — covers how to actually post on dev@ and behave on JIRA without burning trust on day one.