pr-checklist

Files (1)

• SKILL.md

SKILL.md (first lines)

# PR Checklist for OpenMetadata

Self-reviews the branch against `REVIEW.md`, walks through `.github/pull_request_template.md` section by section, gathers evidence, and produces a fully-filled PR description before creating the PR.

## When to Use

- Before running `gh pr create`
- After finishing implementation, before requesting review
- Updating the description of an existing PR that's missing required sections

## Usage

```
/pr-checklist                    # Walk template for current branch vs origin/main
/pr-checklist feature-branch     # Same, for a different branch
/pr-checklist 12345              # Update description of an existing PR
```

## Required Sections (from `.github/pull_request_template.md`)

Every PR must address each section below. Skip with an explicit "Not applicable — <reason>" rather than leaving blank.

1. **Linked issue** — `Fixes #<issue-number>` (GitHub auto-links). No issue → open one first. A test fix needs none (see Step 2).
2. **Type of change** — exactly one box checked.
3. **High-level design** — required for large PRs (new features, refactors, breaking changes, >5 files); skip for small bug fixes.
4. **Tests** — use cases covered, unit tests + coverage %, backend integration tests, ingestion integration tests, Playwright (UI) tests, manual test steps.
5. **UI screen recording** — when creating a PR for a UI feature or feature task with UI impact, run the PR build in Docker with sample data and embed a verified GitHub-hosted video in the description. Use [ui-pr-recording](../ui-pr-recording/SKILL.md); other changes may explain N/A.
6. **Checklist** — every box either checked or explicitly N/A.

## Step-by-Step Workflow

### Step 1 — Inspect the change

```bash
git status
git diff origin/main...HEAD --stat
git log origin/main..HEAD --oneline
```

Use the diff to classify the PR:
- **Creating a PR for a UI feature or a feature task/subtask with UI impact** → Docker run + recording + GitHub upload required. Use task/issue intent and the diff, not just paths or labels. Standalone fixes, refactors, styling, localization, docs, tests and backend-only changes may explain N/A.
- **Touches `openmetadata-service/`** + new/changed REST endpoints → backend integration tests required.
- **Touches Java, a JSON schema, an index mapping, `bootstrap/sql/`, seed data or a pom** → the
  impacted Java tests must pass locally (Step 3). PR CI runs only the unit tests.
- **Touches `ingestion/src/metadata/ingestion/source/`** → ingestion tests required.
- **>5 files changed, or new feature / refactor / breaking change** → high-level design required.
- **Single-file fix with obvious scope** → small change, design section can be `N/A`.

### Step 1b — Self-review against `REVIEW.md`

Every PR is reviewed against `REVIEW.md`. Hold the branch to it first, before Step 3, so the tests
run on the code you will ship. It is not optional, including for small diffs
(ADR:2026-10-16-prs-self-review-against-shared-review-bar).

Before each pass, commit all intended changes, including fixes from the previous pass, so the
branch diff includes them. Pin the reviewed commit with `git rev-parse HEAD`; leave unrelated work
outside the commit.

1. **Review with fresh eyes.** If your harness can start a subagent, start one that has none of your
   session's context, and give it this prompt:

   > Review commit `<reviewed SHA>` in `<absolute path of this checkout>`
   > (`git diff origin/main...<reviewed SHA>`)
   > against `REVIEW.md` at the repository root, as the reviewer that file describes. Follow its
   > "How to review" section. Return the test map (one line per changed source file:
   > `file → test`, or `file → none`), then the findings in its format, 🔴 first. Do not edit files.

   With no subagent, run the same pass yourself: read `REVIEW.md`, then read the diff file by file
   as if someone else had written it.
2. **Act on every 🔴 and every `→ none` on changed behavior.** Fix the code and add the test that
   fails without the fix, or write one line on why the finding does not apply. Nits are optional.
3. **Commit fixes and repeat after any change**, until the committed diff returns no unanswered 🔴.
   Any change to the intended files requires a new commit and pass; the final recorded SHA must
   match the content reviewed.
4. **Record it** for Step 6: the SHA you reviewed, what you fixed, and what you answered instead and
   why.

### Step 2 — Confirm the linked issue

Ask the user for the issue number if not obvious from the branch name or commit messages. Verify it exists:

```bash
gh issue view <issue-number>
```

If no issue exists, stop and ask the user to open one before continuing.

**Exception: a test fix needs no issue.** Don't file an issue for a PR whose purpose is to fix a failing or flaky test. That holds even when the fix lands in the code the test caught rather than in the test itself. For such a PR:

- Replace the template's `Fixes #<issue-number>` line with the test it fixes, e.g. `Fixes the ChartResourceIT.test_bulkCreateOrUpdate_mixedCreateAndUpdate flake`.
- Give it a descriptive title with no issue number.
- Add the `skip-pr-checks` label. "Validate PR Metadata" fails any PR without a linked issue, and this label is the only thing that skips it.

### Step 3 — Gather test evidence

Run the relevant commands and capture output. Don't fabricate coverage numbers — run the tools.

**Backend (Java) — unit and integration tests:** PR checks run only the Java unit tests. The
integration tests run **only in the merge queue**, and JavaUIIT/search-it run nightly. So run the
tests the diff impacts locally with the `java-affected-tests` skill:
```bash
make java_affected                          # impacted unit tests + ITs, by bucket, with the commands
make java_affected_run                      # run them; writes the summary and details to target/java-tests/
make java_affected_run ARGS="--update-pr"   # once the PR exists: summary in the PR body, details in a comment
```
Before the PR exists, paste `target/java-tests/local-pr-results.md` between the
`local-java-test-results` markers under "Backend integration tests"; once it exists, post the
details with `gh pr comment --body-file target/java-tests/local-pr-results-details.md`. Resolve every impact-map gap
and every "no unit test references" class the planner lists (the skill says how). Code and ITs
the branch adds must be owned in the impact map before the PR: `git push` and `gh pr create` are
blocked until `python3 .github/scripts/plan_local_java_tests.py --check-branch` passes. Coverage on
changed classes:
```bash
mvn jacoco:report -pl openmetadata-service
# Coverage HTML: openmetadata-service/target/site/jacoco/index.html
```

**Ingestion (Python):** PR checks run only the unit tests (`py-tests` → "Unit Tests & Static
Checks"); `tests/integration/` runs **only in the merge queue**. So if the diff touches `ingestion/`,

From open-metadata/OpenMetadata, Apache-2.0.

More from open-metadata/OpenMetadata