# Pr Workflow

> Create pull requests for esphome/aioesphomeapi. Use when creating PRs, submitting changes, or preparing contributions.

- Skill: `esphome/pr-workflow-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add esphome/pr-workflow-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/esphome/pr-workflow-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity, Web & Frontend
- Author: esphome (https://skillmd.com/u/esphome)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/esphome/pr-workflow-2

---


# aioesphomeapi PR Workflow

When creating a pull request for `esphome/aioesphomeapi`, follow
these steps. Repo-wide conventions live in
[CLAUDE.md](../../../CLAUDE.md); this skill summarises the parts
that matter at PR-creation time.

## 1. Create branch from origin/main

There is no fork in this workflow — `origin` already points at
`esphome/aioesphomeapi`. Always re-fetch first so the branch is
based on the latest `main`:

```bash
git fetch origin
git checkout -b <branch-name> origin/main
```

## 2. Read the PR template

Before creating a PR, read `.github/PULL_REQUEST_TEMPLATE.md` and
fill in **every** section. The template asks for:

- **What does this implement/fix?** — prose description.
- **Types of changes** — tick exactly one of: `Bugfix`,
  `New feature`, `Breaking change`,
  `Code quality improvements to existing code or addition of tests`,
  or `Other`. Pick the one a future release-notes reader would
  expect; release-drafter slots PRs by label
  (`breaking-change`, `new-feature`, `bugfix`, `enhancement`,
  `documentation`, `dependencies`).
- **Related issue or feature** — `fixes <link>` syntax if
  applicable.
- **Pull request in esphome** — link the companion PR if the
  change requires firmware-side work; mandatory if `api.proto`
  is modified (see step 3).
- **Checklist** — only tick boxes you've actually verified.

## 3. api.proto changes need an upstream PR first

The protocol is defined firmware-side. If the PR modifies
`aioesphomeapi/api.proto`, the matching change MUST land in
`esphome/esphome` first; link the esphome PR in the body and tick
the "linked pull request has been made to esphome" checkbox. After
modifying the proto, regenerate the bindings with the docker image
documented in [CLAUDE.md](../../../CLAUDE.md#regenerating-protobuf-files)
so `api_pb2.py` stays in sync with the protobuf runtime version.

## 4. Commit message conventions

- **Imperative-mood subject line** — "Add X", not "Added X".
- **No `Co-Authored-By: Claude` trailer.** Project preference.
- One logical change per commit; let pre-commit run (ruff lint +
  format). If a hook auto-fixes something, re-stage and re-commit.

## 5. Push and create the PR

**Read `.github/PULL_REQUEST_TEMPLATE.md` from the repo at
PR-creation time and use it verbatim as the body** — do not
reproduce, paraphrase, or trim the template anywhere else, or it
will silently drift out of sync as the template evolves.

When filling in the template:

- Replace the `<!-- ... -->` prompt comments with the actual prose
  for that section. Do not delete anything else.
- **Leave all the checkboxes in place.** Do not remove rows you
  aren't ticking — the auto-labeller and the human reviewer both
  rely on the full list being present.
- Tick exactly one "Types of changes" box. For the Checklist
  section, only tick boxes you have actually verified; leave the
  rest as `- [ ]`.
- **Do not escape characters from the template.** Backticks,
  asterisks, angle brackets, etc. must be passed through verbatim.
  The template is already valid Markdown; do not rewrite it for
  shell quoting. Use `--body-file`, never `--body "..."` with
  shell-escaping.

```bash
git push -u origin <branch-name>
# Read .github/PULL_REQUEST_TEMPLATE.md, fill it in as above,
# write the result to a temp file, then:
gh pr create --repo esphome/aioesphomeapi --base main \
  --title "Imperative subject under 70 chars" \
  --body-file /tmp/pr-body.md
```

The keep-the-checklist-honest rule applies — only tick a checklist
box you've actually verified. "Tests have been added" is verified
by pointing at the new test file in the diff; "linked PR to
esphome" is verified by clicking the link.

## 6. After the PR is open

CI runs ruff (lint + format), the test matrix, and the file-glob
labeller (`.github/workflows/labeler.yml` only auto-labels
`dependencies` based on changed files; the other release-drafter
labels — `bugfix`, `new-feature`, `breaking-change`,
`enhancement`, `documentation` — are applied by maintainers from
the Types-of-changes tick). If a maintainer relabels, that's not
a sign your tick was wrong — it's the editorial slotting for the
release notes.