Skip to content

Record the tooling hazards and the byte-lock rule in the committed docs #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ptr727 merged 3 commits into from
Jul 25, 2026
Merged

Record the tooling hazards and the byte-lock rule in the committed docs #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4786dd1
Record the tooling hazards and the byte-lock rule in the committed docs
ptr727 Jul 25, 2026
08760bb
Make the byte-lock warning consistent with its own exception
ptr727 Jul 25, 2026
fe044f7
Scope the OPERATIONS.md intro to what this file actually owns
ptr727 Jul 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ Operating rules for AI coding agents working in this repository. This file is th

Two companion docs carry the rest. [`OPERATIONS.md`](./OPERATIONS.md) holds the ESPHome operational knowledge an agent needs to change a device config safely - how to reach the ESPHome CLI, how to validate and flash, the template and vendor-firmware patterns, and the traps that have bitten before. [`CODESTYLE.md`](./CODESTYLE.md) holds code style, and [`WORKFLOW.md`](./WORKFLOW.md) the CI/CD workflow contract. Read `OPERATIONS.md` before editing any YAML under this tree.

**Every `##` section here except `Devcontainer` and `Repository Layout` is carried, and must not be edited.** Those carried sections are universal rule text held byte-identical across a fleet of repositories and verified by a hash, so any local change to one registers as drift and fails the repository audit - including a change that fixes a real mistake, and including a new section added in good faith.

`Devcontainer` and `Repository Layout` describe this repository rather than stating a rule, so they are yours to maintain, and `Repository Layout` in particular should be kept current as the tree changes. This intro is repo-owned as well. A rule this repository needs belongs in `OPERATIONS.md` or [`CODESTYLE.md`](./CODESTYLE.md) instead. A genuine defect in the carried text is worth reporting upstream rather than patching locally, and the maintainer supplies the destination - see "Reviewing Carried Fleet Content" in [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) for how to handle one that surfaces in review.

## Foundational Principles

The specific rules in this file implement a few governing principles. Read these first: they are the reason the branching, release, and versioning rules are shaped the way they are, and every rule below serves one of them.
Expand Down
18 changes: 17 additions & 1 deletion OPERATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# ESPHome Operations

How to work on the device configurations in this repository: reaching the ESPHome CLI, validating and flashing a change, the template and vendor-firmware patterns, and the traps that have cost time before. [`AGENTS.md`][agents] carries the cross-cutting rules, this file the ESPHome-specific ones. Read this before editing any YAML under this tree.
How to work in this repository: reaching the ESPHome CLI, validating and flashing a change, the template and vendor-firmware patterns, the tooling hazards, and the traps that have cost time before. [`AGENTS.md`][agents] carries the cross-cutting rules every repository in the fleet shares. Read this file before editing any YAML under this tree, and read [Repository Tooling Hazards][repository-tooling-hazards] before driving `gh` or the repo-config script.

`AGENTS.md` is carried fleet law and byte-locked, so a durable rule specific to this repository cannot live there. It goes in whichever local doc owns the subject: ESPHome operations and repository tooling here, code and documentation style in [`CODESTYLE.md`][codestyle], the CI/CD workflow contract in [`WORKFLOW.md`][workflow].

## Container and CLI

Expand Down Expand Up @@ -207,6 +209,16 @@ The steps below run ESPHome outside the live instance, on a workstation, which i
- Select the default Python interpreter and create a virtual environment, via Ctrl-Shift-P then Python.
- PlatformIO Core installs into the virtual environment and uses that environment's Python.

## Repository Tooling Hazards

Sharp edges in the tooling around this repository, each one learned by tripping over it.

- **Never build a GitHub comment or reply body inside a double-quoted shell string.** Write it to a file and pass `--body-file`, or `-F body=@file` on a REST call. Backticks in a double-quoted string are command substitution, so a body that mentions a path in code formatting **executes that path**. This is not theoretical: a review reply containing `` `repo-config/configure.sh` `` ran the script, which writes by default, and the posted comment came out with its code spans replaced by command output. Escaping each backtick works and is one missed backslash from repeating the incident.
- **[`repo-config/configure.sh`][configure-sh] writes unless told otherwise.** With no arguments it runs in `apply` mode and PATCHes repository settings, toggles Dependabot features, and PUTs both branch rulesets. Pass `check` for the read-only validation, which is what you almost always want: `repo-config/configure.sh check`.
- **Markdown links are reference-style everywhere except [`AGENTS.md`][agents] and `.github/copilot-instructions.md`**, which keep inline links because they are agent-instruction files. Definitions live at the bottom of the file, grouped under `<!-- Repo -->` and `<!-- External -->` and alphabetized within each group. A reference name encodes what it points at, so `analog-max17048-link`, never `analog-en-products-link` after a URL path segment. Removing a link also removes its definition, since an orphan fails the lint.
- **Inline HTML is limited to `<details>` and `<summary>`.** Those two are allowed because a collapsible has no markdown equivalent. Every other element still fails `MD033`, and that includes a `<code>` nested inside a `<summary>` - use a markdown code span there instead.
- **The spell-check gate covers `**/README.md` plus `HISTORY.md`**, wider than the fleet default, so a nested README fails CI like any other. The CI workflow and the `Lint: Spelling` task carry the identical list.

## Things to Avoid

- Do not claim a config change works until `esphome config`, and where appropriate `esphome compile`, returns success.
Expand All @@ -221,12 +233,16 @@ The steps below run ESPHome outside the live instance, on a workstation, which i
[apollo-template]: ./templates/apollo-plt-1b.yaml
[ble-re-playbook]: ./easystart/BLE-RE-PLAYBOOK.md
[ceilsense-template]: ./templates/smarthome-ceilsense.yaml
[codestyle]: ./CODESTYLE.md
[configure-sh]: ./repo-config/configure.sh
[easystart-agents]: ./easystart/AGENTS.md
[easystart-protocol]: ./easystart/PROTOCOL.md
[garage-presence-sensor]: ./garage-presence-sensor.yaml
[repository-tooling-hazards]: #repository-tooling-hazards
[templates]: ./templates/
[test-workflow]: ./.github/workflows/test-pull-request.yml
[vscode-setup]: #vscode-setup
[workflow]: ./WORKFLOW.md

<!-- External -->

Expand Down