Step 9: JIRA and Documentation

The JIRA is the project's permanent memory. The PR is ephemeral — it lives on GitHub, gets merged, fades into git log. The JIRA is what users grep when they hit a similar bug two years later, what release managers read when compiling release notes, what new contributors find when researching prior art. Treating it as a checkbox is the laziest possible thing you can do.

This step is short on procedure and heavy on hygiene. Twenty minutes done well saves three different people an hour each later.

The Status Workflow

Tez uses Apache's standard JIRA workflow. The states you will pass through:

Open  ->  In Progress  ->  Patch Available  ->  Resolved  ->  Closed
                              ^                    ^
                              |                    |
                            (you)              (committer)

Transitioning correctly

• You move it to In Progress when you claim it in Step 1.
• You move it to Patch Available when your PR is open and precommit is green. This is the signal "ready for human review, not just CI."
• You do NOT move it to Resolved. Only a committer does that when they merge. Setting it yourself will be reverted, and you will look new.
• If a committer asks you to revise, the state usually stays at Patch Available. Move back to In Progress only if you'll be rewriting significantly (multi-day rework).

The Patch Available ritual

When you flip to Patch Available, leave a comment:

PR is now open at <link>, precommit is green, ready for review.

Summary: <one paragraph from the PR description>.

Tests: <list>.

Specific reviewer requests: <if any, e.g. "would appreciate a look from
@someone since they wrote the original code">.

This wakes up the JIRA's watchers (committers who follow issues@) and gives them enough context to decide whether to pick it up.

Required Fields

Release Notes

If your fix changes anything a user can observe — output format, config key default, error message, performance characteristic — fill out the "Release Notes" field. Format:

Fixed an issue where vertices with speculatively-populated recovery data
would not transition to SUCCEEDED after all tasks completed. Affects DAGs
submitted via TezClient when checkpoint-based recovery is enabled. No
configuration or API change is required.

Two to four sentences. Past tense ("Fixed"). User-facing language ("DAGs", "TezClient"), not implementation jargon ("V_TASK_COMPLETED handler").

If your fix is purely internal (refactor of a private method, test-only change), leave Release Notes blank. The release manager will skip it.

Linking the PR

Issue Links → "is related to" → Web Link → paste the GitHub PR URL.

Tez also has a bot that auto-links a PR to the JIRA when the PR title starts with TEZ-NNNN:. The bot fires within minutes. If after an hour the JIRA does not have a "GitHub Pull Request" link visible, add it manually:

JIRA → More → Link → Web Link → URL: https://github.com/apache/tez/pull/<NNN> → Link Text: GitHub PR.

Cross-Linking Related JIRAs

If your fix interacts with other tickets, link them explicitly:

Be conservative. Spurious links pollute the issue graph. Cross-link only where the connection is concrete.

Code Comments in the Fix

The JIRA explains what and why at the project level. Inline code comments explain why at the file level for the next person editing this line.

Good inline comment patterns:

// TEZ-NNNN: only short-circuit when recovery replay is actually in progress;
// recoveryData may be populated speculatively at vertex init even when no
// replay will occur. See the JIRA for the affected scenario.
if (recoveryData != null && isReplayingRecovery()) {
  handleRecovery(event);
  return;
}

Rules:

• Cite the JIRA number. Future-you grepping the file for TEZ- will find the context immediately.
• Explain the non-obvious invariant, not what the code obviously does. Never write // increment counter next to count++.
• One or two lines max. If you need a paragraph, write the design note in the class Javadoc or in a markdown doc under docs/.
• Don't paste the entire root-cause document. The JIRA holds that.

Notifying Watchers

After Patch Available, the JIRA's watchers see an email. If you want a specific committer's attention (e.g. the author of the introducing commit from your git bisect), @mention them in a JIRA comment:

[~alice] (author of TEZ-2877) — would appreciate a sanity check on the
recovery short-circuit gating in this PR, since you wrote the original
branch. No urgency.

The [~jira-username] syntax is JIRA's mention. Find the username from their JIRA profile URL (https://issues.apache.org/jira/people/<username>).

Do this once. Do not @-mention in every subsequent comment — committers filter their inboxes.

Backporting Fix to Branches

For most Capstone work, you fix on master and stop. But if your bug affects a maintained release branch and a committer asks you to backport:

1. Comment on the JIRA: "Will backport to branch-0.10 once master patch lands."
2. After merge to master, create a new branch from apache/branch-0.10:

   git fetch apache
   git checkout -b tez-NNNN-branch-0.10 apache/branch-0.10
   git cherry-pick <master-fix-commit-sha>
   # Resolve conflicts (often minor; sometimes major if branch diverged).
   

3. Run validation on the branch (same Step 7 checks).
4. Open a separate PR titled TEZ-NNNN (branch-0.10): <summary> or attach a TEZ-NNNN.branch-0.10.01.patch to the same JIRA.

Each branch's PR/patch is a separate review.

After Merge

When a committer merges your PR:

1. The PR is closed automatically, and they'll comment "Committed to master, thanks @you" with the merged-commit SHA.
2. They (or the bot) set the JIRA to Resolved with Resolution: Fixed and Fix Version: X.Y.Z.
3. You comment with a thanks and any follow-up plans:

   Thanks for the review and merge, [~alice]. I'll watch for the next RC
   to verify it lands cleanly. Filed TEZ-MMMM for the follow-up refactor
   we discussed.
   

4. If you spotted a related improvement during review, file the follow-up JIRA immediately — do not let it slip.

Documentation Beyond the JIRA

Most bug fixes need no further doc. Exceptions:

When in doubt, ask in the JIRA: "Should I update the docs page for X as part of this, or as a follow-up JIRA?" Committers will tell you.

Validation / Self-check

Before advancing to Step 10:

1. JIRA status is Patch Available with a comment summarizing the change and linking the PR.
2. Assignee is you.
3. Component is set to the right module.
4. Affects Version is set to a real Tez version where the bug reproduces.
5. Release Notes field is filled in (or explicitly blank with a one-line "internal only" justification in the PR description).
6. PR is linked under Issue Links → Web Link.
7. Any related JIRAs are cross-linked with the correct relation (is caused by / is related to / etc).
8. Inline code comments cite TEZ-NNNN where the change is non-obvious.
9. If a committer was specifically helpful (author of regressing commit, reviewer on related work), you @-mentioned them once, not repeatedly.