Workflow:Apache Kafka PR Merge And Backport
| Knowledge Sources | |
|---|---|
| Domains | Development_Process, Release_Engineering |
| Last Updated | 2026-02-09 12:00 GMT |
Overview
End-to-end interactive process for Apache Kafka committers to merge pull requests, create properly formatted squash commits, cherry-pick to release branches, and resolve associated JIRA issues.
Description
This workflow documents the kafka-merge-pr.py tool used by Apache Kafka committers to land pull requests into the official Apache repository. The tool automates squash merging with standardized commit messages that include proper JIRA references, author attribution, reviewer credits, and PR closure tags. It optionally supports cherry-picking merge commits to release branches for backporting fixes, and can automatically resolve associated JIRA issues with appropriate fix versions. The tool enforces consistent commit formatting across the project.
Usage
Execute this workflow when you are an Apache Kafka committer ready to merge an approved pull request. You need KAFKA_HOME set to your local Kafka repository, git remotes configured for both the GitHub mirror (PR_REMOTE_NAME) and Apache git repo (PUSH_REMOTE_NAME), and optionally JIRA credentials and a GitHub OAuth key for full functionality.
Execution Steps
Step 1: Fetch PR Metadata
Prompt the committer for a pull request number and fetch metadata from the GitHub API including the PR title, body, source branch, target branch, and author information. The tool also checks PR events to determine if the PR has already been merged by asfgit, preventing duplicate merges.
Key considerations:
- GitHub API access uses GITHUB_OAUTH_KEY if set for higher rate limits
- The tool verifies the PR has not already been closed/merged
- PR metadata is displayed for committer review before proceeding
Step 2: Standardize JIRA References
Normalize the PR title to ensure JIRA issue references follow the standard "KAFKA-XXXX; description" format. The tool detects various common formats (KAFKA-XXXX:, KAFKA-XXXX -, etc.) and converts them to the canonical semicolon-separated format used in Kafka commit messages.
Key considerations:
- The standardization function includes doctests for validation
- Multiple JIRA references in a single title are supported
- The committer can override the standardized title if needed
Step 3: Squash Merge PR
Perform a squash merge by fetching the PR head into a temporary branch, merging it into a copy of the target branch, and collecting all author information from the PR commits. The tool constructs a detailed commit message containing the standardized title, PR body (with Committer Checklist stripped), all authors, reviewers (prompted interactively), and a "Closes #N" line.
Key considerations:
- The merge is performed locally using temporary branches prefixed with PR_TOOL
- All unique authors from PR commits are credited in the commit message
- The committer is prompted to enter reviewer names
- The commit message body has the Committer Checklist section automatically removed
Step 4: Cherry Pick to Release Branches
Optionally cherry-pick the merged commit to one or more release branches for backporting. The tool prompts for a target release branch, fetches it from the remote, and performs a cherry-pick with sign-off of the merge commit. This step can be repeated for multiple release branches.
Key considerations:
- Cherry-pick uses the --signoff flag for proper attribution
- The committer is prompted for each additional release branch
- Merge conflicts must be resolved manually if they occur
- The tool continues to prompt for more branches until declined
Step 5: Push to Remote Repository
Push the merged target branch and any cherry-picked release branches to the Apache remote repository. The tool pushes each branch sequentially with the configured PUSH_REMOTE_NAME.
Key considerations:
- Only pushes to the configured Apache remote, not the GitHub mirror
- Each branch push is confirmed before execution
- The original working branch is restored after all pushes complete
Step 6: Resolve JIRA Issues
Optionally resolve associated JIRA issues by transitioning them to "Resolved" status with appropriate fix versions. The tool uses the jira-python library to connect to the Apache JIRA instance and update issues referenced in the PR title.
Key considerations:
- JIRA credentials are configured via JIRA_USERNAME and JIRA_PASSWORD environment variables
- Fix versions are set based on the target branch(es) the PR was merged into
- This step is optional and skipped if JIRA credentials are not configured
- The tool cleans up all temporary branches regardless of success or failure