branch-pr

When to Use

• Opening a new PR for DBFlux
• Preparing branch changes for review
• Turning local work into a reviewable GitHub PR

Repository Facts

• The PR template lives at .github/pull_request_template.md
• The template sections are: Summary, What does this resolve?, How was this solved?, Validation, Where was this tested?, Checklist, and Labels to apply
• The checklist in the template has five items, including the CHANGELOG.md and label ones — carry all of them over
• Labels to apply is part of the template: it is where the PR names the labels the change needs
• Labels come from the taxonomy in CONTRIBUTING.md § Label Guide (ui:bug, ui:feature, driver:bug, driver:postgres, platform:linux, kind:sql, …); there is no area:* convention
• Labels live on the upstream repository, so a contributor pushing from a fork cannot apply them: state them in the body and let a maintainer apply them during triage
• Use project guidance from AGENTS.md, ARCHITECTURE.md, and CODE_STYLE.md

Critical Patterns

• Inspect git status, branch state, recent commits, and the diff against the base branch before drafting the PR
• Base the PR description on the full branch delta, not only on the latest commit
• Follow the repository template sections exactly when composing the PR body
• In Validation, include only commands or scenarios that were actually run
• In Where was this tested?, mark only real environments; do not claim coverage that did not happen
• Reference linked issues only when they actually exist; do not invent issue requirements
• For a feature or behavior change, check that the linked issue carries the status:approved label before opening the PR; a bug fix does not need it and a PR by the maintainer may skip the check
• Keep each PR around 400 changed lines; split larger work into independent PRs that branch from main rather than stacks, since PRs are squash-merged. New or substantially rewritten code keeps functions under ~100 lines and files under ~1000 lines of production code, with tests in the module's tests submodule. A change that pushes a file past ~1000 lines of production code splits it into a module directory in the same PR, or opens an issue for the split alongside it; files already over the limit are exempt until refactored
• Do not invent labels such as area:*; take them from the taxonomy in CONTRIBUTING.md
• State the labels the change needs in Labels to apply, and do not silently drop the section when the author has no write access to apply them
• Push with git push -u origin <branch> if the branch is not yet tracked

Suggested PR Body

## Summary

- Brief summary of the change

## What does this resolve?

- Resolves #123

## How was this solved?

Short explanation of the approach and tradeoffs.

## Validation

- `cargo check --workspace`
- Manual scenario: ...

## Where was this tested?

- [x] Local development environment
- [ ] Automated tests
- [ ] Linux
- [ ] macOS
- [ ] Windows
- [ ] X11
- [ ] Wayland
- [ ] Other:

## Checklist

- [x] I verified the change against the affected user flow(s)
- [x] I added or updated tests when needed
- [x] I documented follow-up work or known limitations when applicable
- [x] I updated `CHANGELOG.md` under `## [Unreleased]` if this is user-visible
- [x] I applied the appropriate labels (see `CONTRIBUTING.md` § Label Guide)

## Labels to apply

`ui:feature`, `platform:linux`

Pushing from a fork, the last checklist item cannot be ticked by the author: say so where the PR states its labels, and ask a maintainer to apply them.

Commands

# Inspect branch state before creating the PR
git status
git diff --stat
git log --oneline --decorate --graph origin/main..HEAD

# Push branch if needed (to the fork when the author has no write access upstream)
git push -u origin <branch>

# Create the PR against the upstream repository
gh pr create --repo 0xErwin1/dbflux --base main --head <owner>:<branch> --body-file /tmp/pr.md

Resources

• .github/pull_request_template.md
• .github/ISSUE_TEMPLATE/
• CONTRIBUTING.md
• AGENTS.md
• ARCHITECTURE.md
• CODE_STYLE.md