merging-dependabot-prs

# Merging Dependabot PRs ## Overview Dependabot opens bumps against `main` and `support/struts-6-x-x`. Most land as-is. A bump that **ships to users** needs a WW Jira ticket first, and the ticket ID must reach the PR title, the PR body and the squash commit subject before it merges. **Core principle: the decision is driven by the dependency's real Maven scope, not by what Dependabot calls it.** Dependabot's `build(deps-dev):` prefix and its `dependency-type:` trailer are guesses about *its own* ecosystem, not this project's POM. Read the POM. ## The decision Read the semver class from the Dependabot commit trailer — never parse version strings: ```bash gh pr view <N> --json commits --jq '.commits[].messageBody' \ | grep -E 'dependency-name:|update-type:' # update-type: version-update:semver-{patch|minor|major} ``` Then find the real scope, and cross the two: | What is being bumped | patch | minor | major | |---|---|---|---| | GitHub Action (`.github/workflows/*`) | merge bare | merge bare | merge bare | | Maven **plugin** or build tooling (`<build><plugins>`, `*-maven-plugin`, `maven-wrapper`) | merge bare | merge bare | merge bare | | Maven dep, `<scope>test</scope>` | merge bare | merge bare | merge bare | | Maven dep in `apps/` (showcase, rest-showcase) | merge bare | merge bare | merge bare | | Maven dep, **compile / runtime / provided** — including `<optional>true</optional>` | merge bare | **TICKET** | **TICKET** | "Merge bare" always still requires a green build (see below). ### Finding the real scope ```bash grep -rn '<artifactId>NAME</artifactId>' --include=pom.xml . | grep -v /target/ ``` Read the `<scope>` on the surrounding `<dependency>` block in the module that declares it (`core/pom.xml`, `plugins/*/pom.xml`), not the `<dependencyManagement>` copy in `parent/pom.xml` — the managed block usually carries no scope. - No `<scope>` element means **compile** — it ships. - `<optional>true</optional>` still ships: it is published in the module's POM and users who opt in inherit the version. Optional is not exempt. - For a version property (`jackson.version`, `byte-buddy.version`), resolve the property to the artifacts it feeds and take the widest scope among them. ## Is the build actually green? `.asf.yaml` makes exactly one context required per branch: `Build and Test (JDK 17)` on `main`, `Build and Test (8)` on `support/struts-6-x-x`. ```bash gh pr view <N> --json mergeStateStatus,statusCheckRollup --jq \ '"\(.mergeStateStatus) build=\([.statusCheckRollup[] | select((.name // "") | startswith("Build and Test")) | (.conclusion // .state)] | unique | join(","))"' ``` - Green = every `Build and Test *` job is `SUCCESS`. - `continuous-integration/jenkins/pr-merge` is **not** a required context and flakes red ("This commit cannot be built"). `mergeStateStatus: UNSTABLE` with all build jobs green is mergeable. Ignore Jenkins. - Any `Build and Test *` failure, or `mergeStateStatus: BLOCKED` — **stop**. Report it and move on to the next PR. ## Checkpoint — classify, then stop Present one row per open PR and **wait for approval** before any Jira write, title edit or merge. Required columns: | PR | Base | Bump | Semver | Real scope (+ where declared) | Build | Action | Only after approval, run the recipes below. ## Landing a bare bump ```bash gh pr merge <N> --squash --subject "<exact current PR title> (#<N>)" ``` `del_branch_on_merge: true` is set, so no `--delete-branch`. ## Landing a ticketed bump Five steps, in order. All five are required. **1. Create the ticket** — `mcp__asf-issues__jira_create_issue`: ```json { "project_key": "WW", "issue_type": "Dependency", "summary": "Bump <group:artifact or property> from <old> to <new>", "description": "Bump <group:artifact or property> from <old> to <new>", "components": "<affected module>", "additional_fields": "{\"priority\": {\"name\": \"Trivial\"}, \"fixVersions\": [{\"name\": \"<branch release version>\"}]}" } ``` - `components` is its **own** parameter (comma-separated names), not a member of `additional_fields`. `additional_fields` must be a JSON **string**, not an object. - Issue type is **Dependency** — not Task, not Bug. - Component is the module that declares the dep: `Core`, `Plugin - REST`, `Plugin - JSON`, `Unit Tests`, `Build Management`, … - Fix version is the one the latest tickets on the same line already carry: `project = WW AND fixVersion in unreleasedVersions() ORDER BY created DESC`. Not the pom SNAPSHOT: after 6.12.0, `support/struts-6-x-x` read `6.12.1-SNAPSHOT` while its next release was 6.13.0. Not the lowest unreleased Jira version either: a shipped version can stay unreleased in Jira for days. **2. Retitle the PR** — insert the ticket after the conventional-commit prefix, leave every other character alone: ```bash gh pr edit <N> --title "build(deps): WW-XXXX bump org.htmlunit:htmlunit from 4.21.0 to 5.1.0" # ^^^^^^^^ inserted; prefix and remainder verbatim ``` **3. Add the Closes line to the body** — its own paragraph, directly after the first line (`Bumps …`). Some bodies have no release notes and so no `<details>` before the commands footer; anchor on the `Bumps` line, never on `<details>`. Preserve the rest exactly: ``` Bumps [org.htmlunit:htmlunit](https://github.com/HtmlUnit/htmlunit) from 4.21.0 to 5.1.0. Closes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX) <details> ``` **4. Merge with the ticket in the squash subject:** ```bash gh pr merge <N> --squash --subject "build(deps): WW-XXXX bump org.htmlunit:htmlunit from 4.21.0 to 5.1.0 (#<N>)" ``` Without an explicit `--subject`, GitHub takes the subject from Dependabot's *commit* headline and the ticket ID is silently lost from git history. **5. Hand the ticket back, still Open** — list it under the merge report as ready to resolve once *every* PR on it has merged. The ticket workflow belongs to the release manager; do not transition it unless asked. When asked: ```json {"issue_key": "WW-XXXX", "fields": "{\"status\": \"5\", \"resolution\": {\"name\": \"Fixed\"}}", "return_fields": "status,resolution"} ``` `"5"` is the id of the *Resolve Issue* transition. The status name (`"Resolved"`, `"Closed"`) and the transition name (`"Resolve Issue"`) all fail with "Could not find transition"; only the id works. Verified on WW-5755. ## One dependency, two branches, one ticket Dependabot opens the same bump separately against `main` and `support/struts-6-x-x`. Before creating anything, look for the twin: ```bash gh pr list --state open --author app/dependabot --json number,title,baseRefName ``` If a twin exists, create **one** ticket, put it in both PR titles/bodies, and list **both** fix versions on it (WW-5649 carries 6.11.0 and 7.3.0 for PRs #1760 and #1763). It is ready to resolve once both have merged. The twin may already have merged in an earlier run, so `--state open` will not show it. Search Jira too: `project = WW AND issuetype = Dependency AND summary ~ "<artifact>" ORDER BY created DESC`. If the same bump already has a ticket, reuse it and add this branch's fix version to it. ## Scope of this skill Triage and land the queue. Do **not**, as part of it, open follow-up PRs — `dependabot.yml` ignore rules, license-header restorations, test-harness fixes. Report such findings in one line under the table and let the decision be made separately. Any bump with a red build is real compatibility work, not a merge. Report the root cause (first `[ERROR]` lines of the failing `Build and Test` job) and stop. If asked to defer it: file a `Dependency` ticket at the next major with the root cause, then close the PR with a comment that gives the cause, links the ticket, and ends in `@dependabot ignore this major version` — Dependabot replies "OK, I won't notify you…" (Hibernate 7 on #1905, Weld 7 on #1998). That is the ignore rule; no `dependabot.yml` PR. Never push a fix onto a Dependabot branch — Dependabot stops rebasing it, and a source change lands under a ticketless `build(deps):` title. ## Traps | Trap | Reality | |---|---| | "It says `build(deps-dev)`, so it's a dev dependency" | That prefix is Dependabot's guess. `commons-validator` arrives as `deps-dev` and is test scope (true), but the prefix is not evidence — the POM is. | | "`dependency-type: direct:production`, so it ships" | `maven-wrapper` and `hibernate-core` both say `direct:production`; one is build tooling, the other ships. Read the POM. | | "`<optional>true</optional>` means users don't get it" | It is in the published POM and pins the version for anyone who opts in. Optional compile deps need a ticket. | | "git log shows no `WW-` on dependency commits, so titles aren't rewritten" | The squash *subject* historically came from Dependabot's commit headline while the *PR title* carried the ticket. Compare `gh pr view 1746 --json title` against `1f1674411`. Step 4 above exists to close that gap. | | "A red check means don't merge" | Only `Build and Test *` counts. The ASF Jenkins context is not required and flakes red. | | "Both branches need their own ticket" | One dependency, one ticket, two fix versions. | | "The pom says `6.12.1-SNAPSHOT`, so the fix version is 6.12.1" | The pom is a placeholder. Jira's latest tickets on the line carry the real next version. | | "The build is green, so I can just merge it" | Green is necessary, not sufficient. Classify first, and stop at the checkpoint. | ## Red flags — stop and re-read - About to run `gh pr merge` before presenting the classification table and getting approval - About to run `gh pr merge --squash` on a ticketed bump without `--subject` - Classified a dependency from the PR title alone, without grepping the POM for its scope - Creating a second ticket for a dependency that already has an open twin PR - Opening a follow-up PR that nobody asked for - Creating a Jira issue whose type is anything other than `Dependency` - Transitioning a ticket nobody asked you to resolve - Reading the fix version off the pom ## Related - `creating-version-notes` — ticketed bumps appear in the Version Notes Dependency section; bare bumps deliberately do not, and their absence is not a reconciliation gap.