Warning, /swf-testbed/docs/releases.md is written in an unsupported language. File is not indexed.
0001 # Preparing an SWF vNN Release
0002
0003 An SWF `vNN` release is a system release, not the diff of one pull request or
0004 one repository. The release record is the `vNN` entry in
0005 [`RELEASE_NOTES.md`](../RELEASE_NOTES.md).
0006
0007 ## Release scope
0008
0009 The coordinated baseline repositories are:
0010
0011 - `swf-testbed`
0012 - `swf-monitor`
0013 - `swf-common-lib`
0014
0015 Development for a release uses the same `infra/baseline-vNN` branch name in
0016 all three repositories. A repository may have no changes in a particular
0017 release, and its baseline PR may already have merged while work continues in
0018 another repository.
0019
0020 Peer repositories such as `swf-epicprod`, `swf-remote`, and the standalone
0021 agent and worker repositories normally ride `main`; they are not given
0022 matching baseline branches merely for release bookkeeping. Contributors also
0023 normally develop on their own topic or fork branches and merge by PR to
0024 `main`. Relevant peer-repository and contributor work merged during the cycle
0025 is part of the system release and must be included in the review and release
0026 notes.
0027
0028 A release includes:
0029
0030 - all intended changes since the previous baseline in the three coordinated
0031 repositories, including changes already merged to `main` during the cycle;
0032 - relevant changes made during the cycle in peer repositories that ride
0033 `main`;
0034 - operational, deployment, migration, interface, and documentation changes,
0035 not only user-interface features;
0036 - contributor work merged to `main`, credited by name in an Acknowledgments
0037 section when appropriate.
0038
0039 A release does not include uncommitted work, work intended for a later cycle,
0040 or unrelated changes that merely happen to be present in a local worktree.
0041 Release notes describe the resulting capabilities and behavior; they are not
0042 a commit-by-commit diary.
0043
0044 ## Preparation procedure
0045
0046 1. **Set the boundary.** Identify the previous released baseline and the
0047 current `infra/baseline-vNN` branches. Use the previous release merge as the
0048 time boundary for repositories that ride `main`.
0049 2. **Update every checkout.** Fetch or pull the three coordinated repositories
0050 and every peer repository that changed during the cycle. Inspect dirty
0051 worktrees first and preserve unrelated local changes.
0052 3. **Inventory the whole cycle.** Compare the current baseline with the
0053 previous baseline, not only with today's `main`. A `main...HEAD` diff can
0054 omit baseline work already merged earlier in the cycle. For peer
0055 repositories, inspect `main` changes since the release boundary.
0056 4. **Reconcile integration state.** Check which vNN PRs have already merged,
0057 which branches contain follow-up commits, and which repositories have no
0058 delta. Fold the latest `main` into each active baseline branch before its
0059 final PR. If a vNN PR merged early and the same branch later gained intended
0060 vNN work, open a follow-up PR from that branch.
0061 5. **Review outcomes across repositories.** Group the changes by capability or
0062 operational effect. Confirm cross-repository pieces agree: package
0063 ownership, dependencies, migrations, deployment, routes, documentation,
0064 and branch references.
0065 6. **Draft the canonical notes.** Add the newest entry at the top of
0066 `RELEASE_NOTES.md` in `swf-testbed`. Follow the structure and level of prior
0067 entries: a release summary, sections organized by capability or repository,
0068 and acknowledgments. State important compatibility or user-impact facts
0069 explicitly.
0070 7. **Validate the release diff.** Ensure the notes cover every material change
0071 and exclude future-cycle work. Run checks appropriate to the code changed;
0072 documentation-only repositories do not require invented test work.
0073 8. **Publish the coordinated PRs.** Commit only the intended release files,
0074 push each active `infra/baseline-vNN` branch, and open or update its PR to
0075 `main`. Cross-link companion PRs and use the release-note summary in their
0076 descriptions. Do not delete retained baseline branches after merge.
0077 9. **Verify completion.** A repository is merged only when its PR is merged,
0078 and the release is complete only when all intended repository changes and
0079 the canonical release notes are on `main`.
0080
0081 After the release, update the three coordinated checkouts from `main` and
0082 create the next matching `infra/baseline-vNN` branches when the next baseline
0083 cycle begins.
