Record develop-staleness and issue-closing learnings in AGENTS.md#103
Open
ptr727 wants to merge 1 commit into
Open
Record develop-staleness and issue-closing learnings in AGENTS.md#103ptr727 wants to merge 1 commit into
ptr727 wants to merge 1 commit into
Conversation
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Updates AGENTS.md with two durable process learnings for this Docker-only repo: (1) how to handle situations where main receives fixes outside the normal feature -> develop -> main flow, and (2) how to ensure GitHub issue auto-closing triggers on promotion to the default branch.
Changes:
- Document mirroring
main-only fixes back todevelop, including a suggested branch-diff check before relying ondevelop. - Document that
Closes #Nshould be placed on thedevelop -> mainpromotion PR (or closed manually) so the issue closes on merge tomain.
| - **Maintainer-pushed commits on a bot PR auto-disable auto-merge.** The merge-bot's `merge-dependabot` and `merge-upstream-version` jobs only fire on `opened` / `reopened` events (auto-merge is enabled exactly once per PR, for bot-authored PRs that originate from this repository, not forks). When a maintainer pushes commits to a bot's branch (a `synchronize` event with a non-bot actor), the `disable-auto-merge-on-maintainer-push` job fires and calls `gh pr merge --disable-auto`; the maintainer's commits stay in the PR but won't auto-merge with the bot's content. Re-enable manually (`gh pr merge --auto <PR>`) when ready. The merge-bot is on `pull_request_target` with per-PR concurrency; it carries `merge-dependabot`, `merge-upstream-version`, and `disable-auto-merge-on-maintainer-push`. | ||
| - **App-token workflows use Client ID, not App ID.** `actions/create-github-app-token` deprecated the numeric `app-id` input in v3.0.0; the merge-bot and the tracker use `client-id: ${{ secrets.CODEGEN_APP_CLIENT_ID }}` (with `private-key: ${{ secrets.CODEGEN_APP_PRIVATE_KEY }}`). The App token - not `GITHUB_TOKEN` - is required so the merge push is committed by the App and fires downstream workflows (`GITHUB_TOKEN` pushes are blocked from triggering further runs by GitHub's recursion guard). When adding new App-token call sites, use the same form - do not reintroduce `app-id`. | ||
| - **Why parallel dual-target rather than develop-only with eventual flow-through:** consumers pull the Docker image from `main` directly. A develop-only model would leave `main` running a stale ESPHome version during long-running develop features, so both branches receive their own bot updates on their own cadence and each stays current. The upstream ESPHome version *is* the shipped content (it sets the image tag and the installed package), so it must stay fresh on both branches. | ||
| - **Mirror to `develop` any change that lands on `main` outside the feature -> develop -> main flow.** A reconciliation-branch fix made to resolve a `develop -> main` promotion conflict, or a security PR that merges only to `main`, leaves `develop` behind on that content - and forward-only `develop` never back-merges to catch up (the same parallel-target principle as the bots). Before basing new work on `develop`, or diagnosing a defect from it, check `git diff origin/develop origin/main`: a non-empty content diff means develop is stale and the defect may already be fixed on `main`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two durable learnings: mirror main-only fixes to develop (and check git diff origin/develop origin/main before relying on develop), and put Closes #N in the promotion PR. No code changes.