@awebai/oats 0.52.0 → 0.53.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/bin/oats.mjs +304 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/desktop-cli-api.md +673 -58
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +175 -11
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +237 -15
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +49 -19
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/official-catalog.md
CHANGED
|
@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.9.
|
|
13
|
-
| `oats.okf` | `v5.0.
|
|
14
|
-
| `oats.aweb` | `v1.27.
|
|
15
|
-
| `oats.engineering` | `v1.9.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.9.4` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.27.1` | `oats.aweb` (messaging) | |
|
|
15
|
+
| `oats.engineering` | `v1.9.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
|
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
29
29
|
## Find and use packages
|
|
30
30
|
|
|
31
31
|
- A workspace pins an official package by **bare version** in its
|
|
32
|
-
`packages:` map (`oats.okf: v5.0.
|
|
32
|
+
`packages:` map (`oats.okf: v5.0.3`); `oats sync` resolves it through the
|
|
33
33
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
34
34
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
35
35
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.0.
|
|
47
|
+
oats.okf: v5.0.3 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.0.
|
|
51
|
+
- **Bare version** (`v5.0.3`, `5.0.3`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.0.
|
|
54
|
+
convention (`v5.0.3` or `oats-framework/v1.9.4`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.9.
|
|
78
|
-
oats.okf: v5.0.
|
|
79
|
-
oats.aweb: v1.27.
|
|
77
|
+
oats.framework: v1.9.4
|
|
78
|
+
oats.okf: v5.0.3
|
|
79
|
+
oats.aweb: v1.27.1
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.3 ✓ (@ e687a94a)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.27.
|
|
137
|
+
oats package add oats.aweb v1.27.1 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.0.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.0.3",
|
|
164
|
+
"commit": "e687a94a40494521a671979dd168e3d62b11bcde",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
352
|
{
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.3", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.4", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.9.
|
|
362
|
-
resolves to tag `oats-framework/v1.9.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.9.4`
|
|
362
|
+
resolves to tag `oats-framework/v1.9.4`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -9,8 +9,9 @@ The policy it satisfies: no release capability may permanently depend on
|
|
|
9
9
|
GitHub or GitHub Actions. Registry publish works on its own; tags and hosted
|
|
10
10
|
release assets can follow later.
|
|
11
11
|
|
|
12
|
-
The
|
|
13
|
-
released `oats.okf
|
|
12
|
+
The sections after the lane's own cover release-notes entries, the
|
|
13
|
+
post-publish Desktop check, mirroring a released `oats.okf` and releasing
|
|
14
|
+
`oats.framework`.
|
|
14
15
|
|
|
15
16
|
## When to use it
|
|
16
17
|
|
|
@@ -27,13 +28,15 @@ released `oats.okf`.
|
|
|
27
28
|
|
|
28
29
|
Every phase takes `--tag vX.Y.Z` and reads or writes `stage/<tag>/`
|
|
29
30
|
(gitignored; `--stage <dir>` overrides). `MANIFEST.json` there records the
|
|
30
|
-
SHA, the
|
|
31
|
+
SHA, the Node and npm versions it was built with (`node`, `npmVersion`), the
|
|
32
|
+
tarballs and their digests (`npm.tarballs`), the assets, and which phases
|
|
33
|
+
completed.
|
|
31
34
|
Every external command is printed before it runs and its output is logged
|
|
32
35
|
under `stage/<tag>/logs/`; a failing step exits non-zero with the log path.
|
|
33
36
|
|
|
34
37
|
| Phase | Mirrors in `release.yml` | Writes |
|
|
35
38
|
| --- | --- | --- |
|
|
36
|
-
| `build --tag vX.Y.Z [--sha <commit>]` | jobs `build-and-test` and `tests` (the lane runs the suite unsharded): notes gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
|
|
39
|
+
| `build --tag vX.Y.Z [--sha <commit>]` | jobs `build-and-test` and `tests` (the lane runs the suite unsharded): notes gate, unassembled-entries gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
|
|
37
40
|
| `desktop --tag vX.Y.Z --arch arm64\|x64` | one `desktop-build` matrix leg: desktop `npm ci`, `npm test`, `npm run dist -- --<arch>`, strict deep `codesign --verify` (macOS), `dist:smoke` in build-verify mode | `assets/oats-desktop-*` |
|
|
38
41
|
| `stage --tag vX.Y.Z` | publish job, "Checksums" (`shasum -a 256`) | `assets/SHA256SUMS.txt` |
|
|
39
42
|
| `publish-npm --tag vX.Y.Z [--dry-run] --yes` | publish job, the two guarded `npm publish --access public` steps, kernel then adapter | — |
|
|
@@ -59,7 +62,9 @@ through `NPM_CONFIG_USERCONFIG` and deleted afterwards, never into the repo.
|
|
|
59
62
|
## A full release from a Mac plus a Linux host
|
|
60
63
|
|
|
61
64
|
Release notes must exist at `docs/release-notes/<tag>.md` on the commit being
|
|
62
|
-
released,
|
|
65
|
+
released, with no entry file left under `docs/release-notes/next/`
|
|
66
|
+
([Release-notes entries](#release-notes-entries)), and the commit must be on
|
|
67
|
+
`origin/main`. On the Mac:
|
|
63
68
|
|
|
64
69
|
```bash
|
|
65
70
|
git fetch origin
|
|
@@ -123,6 +128,13 @@ Everything after `build` reads `MANIFEST.json` and the files already staged:
|
|
|
123
128
|
so no checks run on it by themselves; close and reopen it to run them, and
|
|
124
129
|
do not read missing checks as green. Open the PR by hand if the workflow
|
|
125
130
|
does not run.
|
|
131
|
+
- **The accepted range also decides which kernel `oats tui` accepts.**
|
|
132
|
+
`ACCEPT_RANGE` (`packages/client/cli-locator.mjs`) is read by the Desktop
|
|
133
|
+
and by the terminal client, which runs the kernel it ships with: a bump
|
|
134
|
+
that leaves the new version outside the range ships an `oats tui` that
|
|
135
|
+
stops at its start with `E_TUI_KERNEL`. The test "the accepted band admits
|
|
136
|
+
the kernel version this Desktop ships with"
|
|
137
|
+
(`packages/desktop/test/cli-locator.test.mjs`) fails for such a bump.
|
|
126
138
|
- **Legs for hosts you do not have.** The Linux AppImage/DEB need a Linux
|
|
127
139
|
host; the lane says so and `stage` lists what is missing.
|
|
128
140
|
- **The packaged window launch.** `release.yml` launches the packaged window
|
|
@@ -143,6 +155,196 @@ logic against fixtures, with `npm` stubbed. The two can run in either order:
|
|
|
143
155
|
a lane release followed by a workflow run, or a broken workflow run finished
|
|
144
156
|
by the lane, and neither republishes what the other already did.
|
|
145
157
|
|
|
158
|
+
## The workflow's actions are named by commit
|
|
159
|
+
|
|
160
|
+
`release.yml` holds the publishing rights, so it names every action it uses
|
|
161
|
+
by a full commit id, with the exact version in a comment beside it:
|
|
162
|
+
|
|
163
|
+
```yaml
|
|
164
|
+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
A tag is the action owner's to move, and a commit is not: the code that runs
|
|
168
|
+
with the publishing rights is the code that was read. `build-installers.yml`
|
|
169
|
+
runs the same installer steps, so it names the same commits. Every other
|
|
170
|
+
workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
|
|
171
|
+
|
|
172
|
+
`test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
|
|
173
|
+
were read has a row for each action: `action`, `id`, `version`. In the two files
|
|
174
|
+
every `uses:` is a row's id, the same action is the same id in both, and the
|
|
175
|
+
comment beside an id is the row's version. In every other workflow a `uses:`
|
|
176
|
+
is the major of a row's version.
|
|
177
|
+
|
|
178
|
+
**An id is moved by a pull request, reviewed like any change to that
|
|
179
|
+
workflow.** It changes these together, and nothing else in the two workflow
|
|
180
|
+
files:
|
|
181
|
+
|
|
182
|
+
- the id and the version comment, on every `uses:` line of that action in
|
|
183
|
+
`release.yml` and `build-installers.yml`;
|
|
184
|
+
- the action's row in the table.
|
|
185
|
+
|
|
186
|
+
**The id is read from an exact version tag of the action's own repository**
|
|
187
|
+
(`v4.4.0`, not the moving `v4`). For an annotated tag it is the commit the tag
|
|
188
|
+
object points at:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
gh api repos/actions/checkout/git/ref/tags/v4.4.0 --jq '.object.type, .object.sha'
|
|
192
|
+
# type `commit`: that is the id. Type `tag`: the id is the tag object's commit:
|
|
193
|
+
gh api repos/actions/checkout/git/tags/<sha of the tag object> --jq '.object.sha'
|
|
194
|
+
|
|
195
|
+
# The same with git. For an annotated tag, the line that ends in ^{} has the id.
|
|
196
|
+
git ls-remote https://github.com/actions/checkout refs/tags/v4.4.0 'refs/tags/v4.4.0^{}'
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Never take an id because it resolves, and never copy one from another
|
|
200
|
+
project's workflow. GitHub resolves `owner/action@<id>` for a commit of any
|
|
201
|
+
fork of that action, so an id that works says nothing about whose commit it
|
|
202
|
+
is. The pull request gives, for each id it moves, the tag, the id and the
|
|
203
|
+
command that read it, so that its reviewer repeats the reading.
|
|
204
|
+
|
|
205
|
+
**The commit is read before its row is written**, for whether the action
|
|
206
|
+
saves or restores an Actions cache by itself: its `action.yml`, the actions
|
|
207
|
+
and packages it depends on, and what its entry points call of a cache.
|
|
208
|
+
|
|
209
|
+
- A composite action names other actions. Check, at the id, that its inner
|
|
210
|
+
`uses:` are full commit ids too: then the outer id fixes them.
|
|
211
|
+
- A version of `actions/setup-node` that caches by itself (v5 and later)
|
|
212
|
+
needs `package-manager-cache: false` on every step. The test takes the
|
|
213
|
+
version of an id from the row, so it refuses a step without it.
|
|
214
|
+
|
|
215
|
+
**The two files name their runners by version too** (`ubuntu-24.04`, as they
|
|
216
|
+
name `macos-14`), never by a label that GitHub moves to another system by
|
|
217
|
+
itself (`ubuntu-latest`). The Linux installers are built on that runner, and
|
|
218
|
+
what they need of a system follows the system that built them.
|
|
219
|
+
`pull-request.yml` keeps `ubuntu-latest` on purpose: when the label moves, a
|
|
220
|
+
break on the new system shows in pull-request CI first and not at a release.
|
|
221
|
+
|
|
222
|
+
The labels the two files may name are a list beside the table of actions in
|
|
223
|
+
`test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and `macos-14`. Every job
|
|
224
|
+
of the two files runs on a label of that list, and both files build on the
|
|
225
|
+
same Linux. A label is added to the list by whoever decides the runner, as an
|
|
226
|
+
action's row is by whoever read it.
|
|
227
|
+
|
|
228
|
+
**Moving the runner is a pull request** that changes the label in the two
|
|
229
|
+
files and in the list together, and says what the installers then need.
|
|
230
|
+
|
|
231
|
+
**What the Linux installer needs today**, to compare with at the next move.
|
|
232
|
+
Read from `oats-desktop-0.52.0-linux-amd64.deb`, built on `ubuntu-24.04`
|
|
233
|
+
(sha256
|
|
234
|
+
`a6148c8a7b49404d73e46c81523568accc560843ed2fab0c54ca501f09c481b7`):
|
|
235
|
+
|
|
236
|
+
| part of the DEB | highest glibc symbol version it needs |
|
|
237
|
+
|---|---|
|
|
238
|
+
| the Electron binary, `oats-desktop` | `GLIBC_2.25` |
|
|
239
|
+
| the native module, `node-pty`'s `pty.node` | `GLIBC_2.34` |
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
ar x oats-desktop-<version>-linux-amd64.deb && tar -xf data.tar.xz
|
|
243
|
+
# for the binary and for each native module under resources/app.asar.unpacked:
|
|
244
|
+
objdump -T <file> | grep -o 'GLIBC_[0-9.]*' | sort -uV | tail -1
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Nothing of the package is run to read it. The numbers are what the DEB's files
|
|
248
|
+
ask of the system's glibc, not a floor anybody tested on an older system. The
|
|
249
|
+
AppImage, built in the same leg from the same build, was not read. The
|
|
250
|
+
module's number follows the runner that builds it: the symbols it needs at
|
|
251
|
+
2.34 are the ones a module gets when it is built on a system whose glibc is
|
|
252
|
+
2.34 or later.
|
|
253
|
+
|
|
254
|
+
## Release-notes entries
|
|
255
|
+
|
|
256
|
+
A release ships one notes file, `docs/release-notes/v<version>.md`. Between
|
|
257
|
+
releases a pull request does not write its entry into it: it adds its entry
|
|
258
|
+
as a file of its own, and one command moves the entries into the notes file
|
|
259
|
+
in the release-prep pull request. Two pull requests that share no code
|
|
260
|
+
therefore never conflict over their entries.
|
|
261
|
+
|
|
262
|
+
### For the author of a pull request
|
|
263
|
+
|
|
264
|
+
- **One file, `docs/release-notes/next/<name>.md`**, added by the pull
|
|
265
|
+
request that makes the change. The entry does not go into
|
|
266
|
+
`docs/release-notes/v<next>.md`, which a pull request touches for one
|
|
267
|
+
reason only, the next point.
|
|
268
|
+
- **Correcting an unreleased entry.** A pull request that makes an existing
|
|
269
|
+
unreleased entry untrue corrects that entry where it stands: in the
|
|
270
|
+
unreleased notes file, or in the entry file of the earlier pull request
|
|
271
|
+
while that file is still under `docs/release-notes/next/`. It adds its own
|
|
272
|
+
entry in its own entry file. In the earlier entry it changes only the
|
|
273
|
+
sentences it makes untrue, and its description names them. A released notes
|
|
274
|
+
file is never corrected this way.
|
|
275
|
+
- **The name** is the issue's number and a short slug:
|
|
276
|
+
`991-update-every-pi-folder.md`. Lower-case letters, digits and hyphens,
|
|
277
|
+
then `.md`. The number is a convention: nothing reads the name but the
|
|
278
|
+
order of assembly.
|
|
279
|
+
- **The content is a piece of the notes file:** one or more `## <Section>`
|
|
280
|
+
headings, each followed by its entries, and nothing else. No title, no text
|
|
281
|
+
before the first heading. Write the entry as it will read in the notes
|
|
282
|
+
file. The sections, in the notes file's order, are `Upgrade`, `Added`,
|
|
283
|
+
`Changed`, `Fixed`, `Removed`, `Provider updates` and `Documentation`. A
|
|
284
|
+
heading is one of them exactly, from the first column.
|
|
285
|
+
- **Links are written for `docs/release-notes/`**, the directory the text
|
|
286
|
+
moves into: a link to `docs/tui.md` has the target `../tui.md`.
|
|
287
|
+
`npm run validate` resolves an entry file's links from that directory. Such
|
|
288
|
+
a link does not resolve when the entry file is opened on its own in a
|
|
289
|
+
browser.
|
|
290
|
+
- **`test/release-notes-entries.test.mjs` holds every entry file on the tree
|
|
291
|
+
to these rules:** the name; a regular file directly in the directory; only
|
|
292
|
+
the seven sections, each at most once; at least one non-blank line under
|
|
293
|
+
each heading; no `# ` title; every fenced block closed. A `## ` line inside
|
|
294
|
+
a fenced block is text.
|
|
295
|
+
- **The directory exists only while it holds entries.** It has no README and
|
|
296
|
+
no placeholder: anything in it counts as an unassembled entry.
|
|
297
|
+
|
|
298
|
+
### For the tag owner
|
|
299
|
+
|
|
300
|
+
```bash
|
|
301
|
+
node scripts/assemble-release-notes.mjs --tag v0.54.0
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
- **It moves every entry into `docs/release-notes/v0.54.0.md`** and removes
|
|
305
|
+
the entry files and the emptied directory. A notes file that does not exist
|
|
306
|
+
is created, with the title `# OATS 0.54.0` and the line `Unreleased`.
|
|
307
|
+
`--root <dir>` works in another tree.
|
|
308
|
+
- **Order.** Files are taken by name as plain strings, what `LC_ALL=C ls`
|
|
309
|
+
prints: `1002-…` comes before `996-…`. In each section a file's text goes
|
|
310
|
+
after what the section already holds. A section the notes file lacks is
|
|
311
|
+
created at its place in the order above. A heading that is not one of the
|
|
312
|
+
seven, such as a hand-written highlight, stays where it is.
|
|
313
|
+
- **It moves text and rewrites none.** Every line it did not add is kept as
|
|
314
|
+
it is, except blank lines where text goes in. It sets no date in place of
|
|
315
|
+
`Unreleased` and sorts nothing inside a section: reorder entries by hand in
|
|
316
|
+
the prep pull request, where the result is reviewed as a diff.
|
|
317
|
+
- **All or nothing.** With a problem in any entry, or a notes file that holds
|
|
318
|
+
a section twice or a fenced block that is never closed, it prints every
|
|
319
|
+
problem, writes nothing, removes nothing and exits 2.
|
|
320
|
+
- **An interrupted run.** The command writes the notes file first and removes
|
|
321
|
+
the entry files after it. A run that stops in between leaves entry files
|
|
322
|
+
beside a notes file that already holds their text, and a second run would
|
|
323
|
+
add that text again. Put the tree back first, one of two ways: delete the
|
|
324
|
+
entry files that are left, whose text the notes file holds, and the run is
|
|
325
|
+
complete; or return all of `docs/release-notes/` to what Git has, which is
|
|
326
|
+
the notes file (deleted, if this run created it) and the entry files
|
|
327
|
+
already removed, and run the command again. A run that stops before it
|
|
328
|
+
writes the notes file has changed neither; at most it leaves a `.tmp` file
|
|
329
|
+
beside the notes file.
|
|
330
|
+
- **Running it more than once in a release is normal.** The pull request that
|
|
331
|
+
moves the manifests to a new version runs it to create that version's notes
|
|
332
|
+
file, which `test/release-packaging.test.mjs` requires for the version the
|
|
333
|
+
manifests carry. The release-prep pull request runs it again for the
|
|
334
|
+
entries merged since, which go after the earlier ones.
|
|
335
|
+
- **A tag is refused while anything is under `docs/release-notes/next/`:** by
|
|
336
|
+
the `build-and-test` job of `release.yml` and by `release-lane.mjs build`,
|
|
337
|
+
each right after its notes-file gate and before anything is built. Each
|
|
338
|
+
names the command to run. The kernel package carries all of `docs/`, so
|
|
339
|
+
these two gates are also what keeps an unassembled entry out of a published
|
|
340
|
+
tarball.
|
|
341
|
+
|
|
342
|
+
### When it starts
|
|
343
|
+
|
|
344
|
+
When the change that adds this section is on `main`. Entries already in
|
|
345
|
+
`docs/release-notes/v0.53.0.md` stay there. A pull request in flight that has
|
|
346
|
+
to rebase for the notes anyway may move its entry into a file at that rebase.
|
|
347
|
+
|
|
146
348
|
## Desktop release verification
|
|
147
349
|
|
|
148
350
|
Installer CI gates what headless runners can prove reliably for every
|
|
@@ -247,7 +449,9 @@ When the diff is not empty:
|
|
|
247
449
|
|
|
248
450
|
1. **The framework prep PR.** Bump `version` in the `oats.json` of each
|
|
249
451
|
changed capability and in `oats-package/oats-package.json`, and add the
|
|
250
|
-
release-notes entry
|
|
452
|
+
release-notes entry as a file under `docs/release-notes/next/`
|
|
453
|
+
([Release-notes entries](#release-notes-entries)). Read the skill lines
|
|
454
|
+
added since the last tag: a
|
|
251
455
|
command or behaviour that an older kernel the capability still admits does
|
|
252
456
|
not have names the version it starts in. Guidance text alone does not
|
|
253
457
|
raise a capability's `compatibility.oats`.
|