Community Interaction

This chapter covers the operational mechanics of communicating with the Apache Tez community — dev@tez.apache.org, JIRA, and GitHub pull requests. Most of the rules below are not Tez rules; they are Apache-wide conventions that 25 years of mailing lists have settled into. Violating them is not a hanging offence, but it marks you as new and spends a little of the credibility you have not yet earned.

The one thing that makes Tez different from a busy project is traffic. As the section index established, this is a maintenance-phase project with roughly two active committers. That single fact reshapes every interaction below: latency is measured in weeks, a single reviewer sees almost everything, and a contributor who is calm, patient, and self-sufficient stands out immediately.

The Lists

Tez has the standard ASF list set. The addresses are verifiable — the notification routing in .asf.yaml names commits@tez.apache.org and issues@tez.apache.org directly, and pull requests are routed to issues@ as well.

Subscribe by sending empty mail to <list>-subscribe@tez.apache.org and confirming the reply. Unsubscribe via <list>-unsubscribe@tez.apache.org. Default for a new contributor: subscribe to dev@ and user@; add issues@ once you are actively tracking a JIRA. Note that on this project issues@ carries both JIRA activity and GitHub PR activity — that is the .asf.yaml routing (pullrequests: issues@tez.apache.org), and it is how the committers see your PR at all.

Mail Etiquette: Subject Prefixes

Subject lines on dev@ use ASCII-bracketed prefixes so subscribers can filter. Use them.

Examples of good subjects:

• [DISCUSS] Promoting a config default: enabling auto-parallelism by default
• [VOTE] Apache Tez 0.10.5 RC0
• [ANNOUNCE] New Tez committer: NAME

Mail Etiquette: Formatting

The ASF lists are plaintext-first. The hard rules:

1. Plain text only. No HTML, no rich text. Set "send as plain text" as the default for *@apache.org.
2. Inline reply, not top-post. Quote the relevant lines; reply below each.
3. Wrap at ~78 columns. Long unbroken lines render badly in the archives.
4. Sign off with a first name, not a corporate signature block.
5. No attachments over a few KB. Patches go on the JIRA/PR, not the list.
6. No images. Diagrams as ASCII or as links.

A good dev@ reply quotes what it answers and adds signal:

On Tue, May 7, 2024 at 10:14 AM, Foo Bar <foo@example.com> wrote:
> Should we bump tez.am.resource.memory.mb default from 1024 to 2048
> to handle large DAGs better?

Agreed for large DAGs, but 2048 doubles the AM footprint for everyone
running small jobs (most CI users). Could we size it off DAGPlan size,
falling back to 1024? I can prototype on a JIRA if there's interest.

--
Jane

What it doesn't have: HTML, a disclaimer, an inline screenshot, or a bare "+1" with no context.

JIRA and PR Etiquette

JIRA is the system of record; the GitHub PR is how code is delivered today. Both have mores.

Don't reassign

The Assignee field belongs to whoever is doing the work. If a JIRA is assigned to someone else, do not reassign it to yourself, even if it has been idle for a year — and on a maintenance-phase project, many are idle for years. Comment first:

Hi @ASSIGNEE, I'd like to pick this up if you're not actively working on it. Happy to hand back if you have an in-flight patch. If I don't hear back in a week or two I'll assign it to myself.

After a genuine wait (two weeks is reasonable here, given the pace), then take it. Nobody will be offended; they will more likely be glad someone is moving it.

The current delivery flow: JIRA + GitHub PR

Here is the real, current workflow, reconstructed from recent history rather than from an old wiki page:

1. Open (or claim) a TEZ-NNNN JIRA. GitHub Issues is disabled (.asf.yaml issues: false), so JIRA is the only tracker.
2. Open a GitHub PR against apache/tez whose title starts with the JIRA key, e.g. TEZ-4700: [Cloud] Single image shared between AM and Task. The Yetus/Jenkins integration keys off the ^TEZ-[0-9]+$ pattern (see dev-support/tez-personality.sh).
3. CI runs automatically. GitHub Actions (.github/workflows/build.yml) builds on a matrix of JDK 21/25 × Ubuntu/macOS; a separate Apache Yetus/Jenkins run does the full unit tests and static analysis on every PR (that was the point of TEZ-4718, "ensure full build and UT run on every PR").
4. A committer reviews. On this project that is almost always one of the two active committers. Iterate by pushing more commits to the PR branch.
5. Merge is a squash. .asf.yaml enables only the squash button, so your PR becomes one commit whose message ends (#NNN) (<you> reviewed by <reviewer>). That reviewed by line is the permanent record of who vouched for your change.

You will still meet the classic workflow in old JIRAs: attached patch files named TEZ-NNNN.001.patch, TEZ-NNNN.002.patch, re-rolled each round, with status set to Patch Available. That is history, not current practice — but "Patch Available" as a status still signals "ready for review" if you use JIRA workflow states. Don't attach raw .patch files today; open a PR.

"Patch Available" / "ready for review" semantics

Whatever the mechanism, signalling "ready for review" means all of: the change applies to current master; you believe tests pass locally; and you are actually requesting review — not still iterating. If your PR is a draft, mark it a GitHub draft and say so; don't ping a committer to review something you're still changing.

Interacting With a Low-Traffic, Mature Project

This is the part generic open-source advice gets wrong for a project like Tez. Calibrate your expectations to the real pace:

• Latency is weeks, not days. With ~two active committers, a PR can sit green for a couple of weeks before anyone looks. This is normal and is not a snub. Do not interpret silence as rejection.
• One reviewer sees almost everything. Grep the log — git log --oneline | grep -c "reviewed by Laszlo Bodor" — and you'll see how concentrated review is. That means your reviewer is chronically time-constrained. Make their job trivial: small PRs, green CI, a clear description, a linked JIRA. A reviewer who can approve in five minutes will; one who has to reverse-engineer your intent will defer it, and "defer" on this project means months.
• Self-sufficiency is currency. The most valuable new contributor is the one who needs the least hand-holding. Show your investigation (next section), propose a fix, and make the committer's only job to say "+1."

How to unstick a stalled review, politely

Escalation is legitimate; impatience is not. The cadence for Tez's pace:

1. Wait a real interval. A couple of weeks of silence on a green PR is within normal range. Do not ping after two days.
2. First nudge — on the PR/JIRA, factual and specific:

   Friendly ping — this has been green for two weeks and addresses TEZ-NNNN. Anything you'd like changed, or is it just waiting on a reviewer? Happy to rebase if master has moved.

3. Then, a short pointer on dev@ if the PR nudge goes unanswered for another week or two: a one-line "could a committer take a look at TEZ-NNNN / #NNN when you get a chance?" is fine. Do not re-litigate the change on the list; just point at it.
4. Never: ping daily, @-mention every committer, rewrite the PR title to "PLEASE REVIEW," or argue your change is more important than others in the queue.

The single best unsticking move is not a ping at all — it is reviewing someone else's PR. On a two-committer project, a contributor who leaves a careful, correct review on another PR becomes visible fast, and that visibility is what gets your own work looked at. It is also the first rung of the path to committership.

Asking a Good Question: Show Your Investigation

The pattern that gets answers on a low-traffic list is "here is what I found, here is my question" — never "how does X work?" Compare.

Weak (will be ignored or get "please investigate first"):

Subject: How does auto-parallelism work?

Hi, can someone explain how Tez decides the number of reducers?

Strong (shows homework, gives the committer a five-minute answer):

Subject: [DISCUSS] ShuffleVertexManager auto-parallelism: why does it never
         increase parallelism?

I've been reading ShuffleVertexManager (traced from TEZ-338/TEZ-398 through
the TEZ-3395 refactor) and the tests in TestShuffleVertexManager. My reading
is that auto-parallelism only ever *decreases* task count toward
tez.shuffle-vertex-manager.desired-task-input-size, never increases it, and
that ENABLE_AUTO_PARALLEL defaults to false.

Question: is the "decrease-only" behavior a deliberate design choice (avoid
re-partitioning cost?) or just what was implemented? I ask because <concrete
use case>. If it's deliberate, I'll document it; if it's open, I'd like to
file a JIRA to explore increase-on-skew.

I've read TEZ-3303 (precise partition stats) but didn't find a JIRA that
settles the decrease-only question — pointer appreciated.

The strong version names the classes and JIRAs you read, states your current understanding so a committer can correct one sentence instead of writing an essay, gives a concrete motivation, and ends with a focused question. It also demonstrates you can already navigate the code — which makes the committer far more willing to spend time on you. This "show your investigation" pattern is the highest-return communication habit in this chapter.

A Good user@ Question

For usage questions on user@, give versions, symptom, reproduction, what you tried, and one focused question:

Subject: Tez 0.10.x: AM OOM on submission of a 200-vertex DAG

Versions: Tez 0.10.4, Hadoop 3.3.6, Hive 3.1.3, JDK 11
Symptom:  TezClient.submitDAG throws OOM ~12s in; AM log shows GC overhead
          limit inside DAGImpl.init.
Repro:    submit a DAG with 200 vertices, each with 5 inputs;
          tez.am.resource.memory.mb = 1024 (default)
Tried:    bumping to 2048 works; reducing parallelism works around it.
Question: is there a known scaling limit for DAGPlan size at the default AM
          memory, and should the default scale with plan size?
Logs:     <link to a gist>

A question missing any of these gets a "please provide more info" reply, costing a round-trip that on this project is a week.

Apache-Wide Norms at Tez Scale

Two Apache concepts govern how decisions actually get made, and the Tez bylaws (docs/src/site/markdown/by-laws.md) spell out exactly how they apply here.

Lazy consensus. Most things happen without a formal vote. A code change carries "lazy approval and then lazy consensus" with active committers holding the binding votes — in practice, one committer's +1 (approving your PR) is enough, absent an objection. New committers and new PMC members are added by lazy consensus of active PMC members. "Lazy" means silence is assent: if you post a reasonable proposal to dev@ and nobody objects within the voting window, it passes. On a quiet list, learn to drive things to a decision by stating "if there are no objections by <date> I'll proceed" — otherwise a proposal can drift forever in the absence of anyone actively saying no.

Vetoes. A -1 on a code change is a veto, and per the bylaws it "must be accompanied by a valid reason." A valid, binding veto cannot be overruled — the vetoed change must be reversed until the objection is resolved. This sounds dramatic but is rare; its practical effect is cultural: it means any active committer can block a change they believe is wrong, so the norm is to earn agreement rather than push through. A -1 without a technical reason is void. If you receive one, do not argue tone — ask "what would change your mind?" and address the substance.

Voting timeframes. Formal votes (releases, for example) run a minimum of 3 days, excluding weekends; full-consensus or 2/3-majority votes run a minimum of a week. Don't expect a same-day answer to anything that requires a vote — and see the Release & PMC section for the full mechanics.

Validation Artifacts

After this chapter you should have:

1. A subscription confirmation to dev@tez.apache.org and user@tez.apache.org.
2. A "show your investigation" question drafted for a real thing you're unsure about, in the strong format above.
3. One inline (not top-posted) reply to an existing dev@ thread.
4. A ~/tez-notes/etiquette.md cheatsheet with the subject-prefix table and the current JIRA+PR delivery flow.
5. The output of git log --oneline | grep -c "reviewed by" — your one-number proof of how concentrated review is on this project.

The next chapter — Patch Quality — is what your PR needs to look like so that scarce reviewer can approve it in five minutes.