diff --git a/AGENTS.md b/AGENTS.md index a511bba..bc90b4c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,10 +11,16 @@ release metadata, tags, or GitHub settings. `develop`. Ordinary development requests do not authorize promotion to `main`. - Inspect git status before editing and preserve unrelated work. Stage only your changes; never discard or commit unrelated user changes. -- Never force-push `main` or `develop`, delete either branch, move published - release tags, change the default branch, or bypass CI as a routine fix. -- Unlocking or moving `main` requires an explicit release instruction from the - owner. Keep it locked throughout ordinary development and review. +- Use rebase merging for all PRs. Do not create merge commits or squash commits; + rebase feature branches onto the current target branch when updating them. +- History rewriting is allowed for rebase and history cleanup. Fetch first, + inspect the affected commits, and push with + `--force-with-lease` bound to the expected remote SHA, never plain `--force`. + Preserve unrelated work and rerun required checks on rewritten revisions. +- Never delete `main` or `develop`, move published release tags, change the + default branch, or bypass CI as a routine fix. +- Unlocking or moving `main` requires an explicit release or history-repair + instruction from the owner. Relock it immediately after the authorized work. ## CI and delivery @@ -25,6 +31,8 @@ release metadata, tags, or GitHub settings. - Before merging, both GitHub checks `test` and `windows-check` must pass on the current PR revision, with the branch up to date and conversations resolved. No additional reviewer is required for this solo-maintainer repository. +- Rebase merge with the checked head SHA. For an authorized integration-branch + rewrite, follow the lease and protection-restoration steps in RELEASING.md. - Fix failures without weakening, skipping, or renaming required checks to evade protection. Read-only job permissions are the default. - The bootstrap checks validate repository content and the validation tools on diff --git a/README.md b/README.md index 8052b5f..1ebc10e 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ migration requirements, and acceptance criteria. ## Development -Use a feature branch from `develop` and open a PR back to `develop`. `main` +Use a feature branch from `develop` and rebase merge its PR into `develop`. `main` remains locked between authorized releases. See [AGENTS.md](AGENTS.md) and [the development and release workflow](docs/RELEASING.md). diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 433db0c..e7681e8 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -5,11 +5,10 @@ This repository contains project scaffolding. It has no standalone application, package, release version, or Omarchy marketplace submission yet. -The initial CI/workflow setup is a one-time bootstrap: merge the setup PR into -`develop` after both checks pass, then merge a bootstrap PR from `develop` into -`main` after both checks pass. Lock `main` immediately afterwards. This is not -an application release and creates no release tag. Future promotion requires -an explicit release instruction from the owner. +The initial CI/workflow bootstrap is complete. Its history was subsequently +linearized at the owner's request. This is not an application release and +creates no release tag. Future promotion requires an explicit release +instruction; repairing existing history is governed separately below. ## Development @@ -20,15 +19,39 @@ an explicit release instruction from the owner. `python3 -m unittest discover -s tests -v`. 3. Push the feature branch and open a PR targeting `develop`. 4. Wait for `test` and `windows-check` on the current PR revision. Resolve - conversations and update from the base branch when GitHub requires it. -5. Merge through the PR without admin bypass. Keep working from `develop`. + conversations and rebase onto the base branch when GitHub requires it. +5. Rebase merge through the PR using its checked head SHA, without admin bypass. + Do not use merge commits or squash merging. Keep working from `develop`. Both integration branches require up-to-date checks, PRs, resolved -conversations, and administrator enforcement. They prohibit force pushes and -deletion. This is a solo-maintainer workflow: zero additional approvals are +conversations, administrator enforcement, and linear history. Force pushes are +enabled for history rewriting; branch deletion remains prohibited. This is a +solo-maintainer workflow: zero additional approvals are required. `main` has an additional lock between releases and remains the default. Tags matching `v*` cannot be updated or deleted, including by administrators. +## History rewriting + +History may be rewritten for rebasing and cleanup; do not rewrite unrelated +work or published version tags. An explicit owner instruction is required to +unlock or rewrite `main` outside a release. + +1. Fetch current refs, inspect local status and the affected history, and record + the expected full remote SHA. Do not create backup bundles unless requested. +2. Prepare linear replacement commits and verify the intended tree changes. + Run local checks and obtain passing GitHub checks for the replacement SHA + before updating an integration branch. +3. Use `--force-with-lease=refs/heads/BRANCH:EXPECTED_SHA`, never plain force. + If the lease fails, stop and reconcile new remote work; do not replace the + expected SHA blindly. +4. Required checks and linear history remain enforced. If GitHub's PR rule + blocks an explicitly authorized ref repair, temporarily lift only that PR + requirement on the affected branch for the repair, then restore it in a + `finally` block. Do not use this exception for ordinary feature delivery. + Unlock `main` only for the authorized operation and relock it immediately. +5. Read back the branch SHA and protections, verify push CI on the resulting + revision, and update the local checkout without discarding uncommitted work. + ## What CI proves today `test` runs on Ubuntu and `windows-check` runs on a native Windows runner. @@ -52,14 +75,14 @@ real packaging; there are currently no installable artifacts to publish. 1. Obtain an explicit release instruction. Prepare the version, changelog, package contents, dependency declarations, installation/migration/removal instructions, and recovery validation on a feature branch from `develop`. -2. Pass relevant local suites and GitHub checks. Merge into `develop`, then open +2. Pass relevant local suites and GitHub checks. Rebase merge into `develop`, then open a release PR from `develop` into `main`. Do not include unfinished features. 3. Wait for all required checks on the release PR's current revision. Leave `main` locked during preparation and review. 4. For the authorized promotion only, unlock `main` while retaining required - PRs, checks, and administrator enforcement. Merge the release PR once and + PRs, checks, and administrator enforcement. Rebase merge the release PR once and immediately lock `main` again. If promotion fails, restore the lock before - other work. Read back the protection settings and record the full merge SHA. + other work. Read back the protection settings and record the resulting full SHA. 5. Verify the push checks on that exact `main` SHA. Create a new version tag pointing to it and publish the reviewed artifacts and release notes. Never move an existing release tag.