|
| 1 | +# Release Modes |
| 2 | + |
| 3 | +This document names the release modes used by `socket` so maintainer work follows the same local-first shape as `productivity-skills:maintain-project-repo` while still respecting `socket`'s mixed monorepo and subtree responsibilities. |
| 4 | + |
| 5 | +## Mode Summary |
| 6 | + |
| 7 | +Use `standard` when the release belongs only to the `socket` superproject. Use `subtrees` when the release also needs explicit accounting for subtree-managed child repositories. |
| 8 | + |
| 9 | +Both modes treat `socket` as the release owner for the umbrella repository: |
| 10 | + |
| 11 | +1. make the intended commits |
| 12 | +2. validate the changed surface |
| 13 | +3. publish through a branch and pull request when the change is not already on `main` |
| 14 | +4. check CI and fix failures before continuing |
| 15 | +5. check PR comments and requested changes before continuing |
| 16 | +6. merge to `main` |
| 17 | +7. fast-forward local `main` |
| 18 | +8. create the `socket` tag locally from the reviewed `main` |
| 19 | +9. push the tag |
| 20 | +10. create the GitHub release from the existing tag |
| 21 | +11. verify `git log origin/main..main` is empty |
| 22 | +12. account for every local branch not contained by `main` |
| 23 | + |
| 24 | +The difference is that `subtrees` adds a child-repository sync gate before tagging or before claiming the release is done. |
| 25 | + |
| 26 | +## Standard Mode |
| 27 | + |
| 28 | +Use `standard` for root docs, root marketplace metadata, root validation scripts, monorepo-owned child directories, and shared version bumps that do not need child-repository subtree synchronization. |
| 29 | + |
| 30 | +Standard mode should feel like the protected-main flow from `maintain-project-repo`: changes land through the normal `socket` branch or local-main path, CI and review comments are cleared before tagging, local `main` is fast-forwarded after merge, and the tag is created from the reviewed `main` commit. |
| 31 | + |
| 32 | +The root version helper remains a version-surface tool, not the full release driver: |
| 33 | + |
| 34 | +```bash |
| 35 | +scripts/release.sh inventory |
| 36 | +scripts/release.sh patch |
| 37 | +scripts/release.sh minor |
| 38 | +scripts/release.sh major |
| 39 | +scripts/release.sh custom 1.2.3 |
| 40 | +``` |
| 41 | + |
| 42 | +After a version bump lands on `main`, create the matching `vX.Y.Z` tag from `main`, push it, and create the GitHub release with `gh release create --verify-tag`. |
| 43 | + |
| 44 | +## Subtrees Mode |
| 45 | + |
| 46 | +Use `subtrees` when a `socket` release also changes, imports, refreshes, or depends on one of the remaining subtree-managed child repositories. |
| 47 | + |
| 48 | +Subtrees mode is standard mode plus this extra gate: |
| 49 | + |
| 50 | +1. identify each subtree-managed child touched by the release |
| 51 | +2. classify each touched child as `pull-only`, `push-out`, or `no subtree action` |
| 52 | +3. run the required subtree pull or push before tagging `socket`, or record why no subtree action is correct |
| 53 | +4. rerun root validation after any subtree operation |
| 54 | +5. re-check `git log origin/main..main` and `git branch --no-merged main` before cleanup or final status |
| 55 | + |
| 56 | +This mode is not the same as `maintain-project-repo`'s `submodule` mode. `socket` is still the umbrella repository being released, not a child checkout waiting for a parent pointer update. |
| 57 | + |
| 58 | +## Current Subtree Policy |
| 59 | + |
| 60 | +| Child | Prefix | Remote | Direction | Rule | |
| 61 | +| --- | --- | --- | --- | --- | |
| 62 | +| `apple-dev-skills` | `plugins/apple-dev-skills` | `apple-dev-skills` | pull and push | Work may start in `socket`; push back with `git subtree push` when the child repo should receive the socket-authored change. | |
| 63 | +| `SpeakSwiftlyServer` | `plugins/SpeakSwiftlyServer` | `speak-swiftly-server` | pull-only | Build, validate, tag, release, and live-refresh in the standalone SpeakSwiftlyServer checkout, then pull the merged child state into `socket`. Do not subtree-push SpeakSwiftlyServer from `socket` unless Gale explicitly overrides this rule. | |
| 64 | + |
| 65 | +## Subtrees Mode Checklist |
| 66 | + |
| 67 | +Before opening or merging the `socket` release PR: |
| 68 | + |
| 69 | +- verify which subtree-managed children are touched |
| 70 | +- for `SpeakSwiftlyServer`, verify the standalone checkout already owns the child release or say plainly that the socket sync is intentionally deferred |
| 71 | +- for `apple-dev-skills`, decide whether the socket commit must be pushed back to the child remote before the umbrella release |
| 72 | +- keep subtree sync commits isolated from unrelated docs, marketplace, or version-bump commits |
| 73 | + |
| 74 | +Before tagging `socket`: |
| 75 | + |
| 76 | +- confirm the subtree policy table above was followed |
| 77 | +- run `uv run scripts/validate_socket_metadata.py` |
| 78 | +- confirm local `main` is fast-forwarded to `origin/main` |
| 79 | +- confirm `git log origin/main..main` is empty |
| 80 | +- enumerate every local branch not contained by `main` and account for each one |
| 81 | + |
| 82 | +After tagging: |
| 83 | + |
| 84 | +- push the `socket` tag |
| 85 | +- create the GitHub release from the existing tag |
| 86 | +- verify the release object exists on GitHub |
| 87 | +- if a child release landed outside `socket`, verify `socket` either contains that child state or explicitly records why the sync is deferred |
0 commit comments