@sovereignfs/create 0.13.0 → 0.14.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 +11 -0
- package/dist/create.mjs +871 -30
- package/package.json +1 -1
- package/template/app/AGENTS.md +49 -0
- package/template/app/CHANGELOG.md +11 -0
- package/template/app/CLAUDE.md +9 -0
- package/template/app/CONTRIBUTING.md +41 -27
- package/template/app/README.md +5 -1
- package/template/app/RELEASING.md +31 -0
- package/template/app/_github/repository.json +50 -0
- package/template/app/_github/workflows/ci.yml +11 -3
- package/template/app/_github/workflows/promotion.yml +24 -0
- package/template/app/_github/workflows/publish.yml +56 -7
- package/template/app/_github/workflows/release.yml +40 -0
- package/template/components/RELEASING.md +27 -0
package/package.json
CHANGED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Guidance for every AI agent working on **TITLE** (Claude Code reads it through `CLAUDE.md`). The sections above and below the shared one are
|
|
4
|
+
this app's own; the shared one is written by `npm create @sovereignfs app sync` and is the same in every app of the suite.
|
|
5
|
+
|
|
6
|
+
## What this is
|
|
7
|
+
|
|
8
|
+
**TITLE** is an app for a [Sovereign](https://github.com/sovereignfs/sovereign) instance. Say here what it does and for whom.
|
|
9
|
+
|
|
10
|
+
## Source of truth
|
|
11
|
+
|
|
12
|
+
- `README.md`: what is here, how to build, host and run it.
|
|
13
|
+
- `sovereign.manifest.json`: what an instance needs to know to host it.
|
|
14
|
+
- `CONTRIBUTING.md` and `RELEASING.md`: how work lands and how a version is released.
|
|
15
|
+
|
|
16
|
+
<!-- sovereign:shared:begin -->
|
|
17
|
+
|
|
18
|
+
## Working conventions (shared by every app of the suite)
|
|
19
|
+
|
|
20
|
+
- **Two branches.** Work lands on `develop`, committed directly or through a feature branch (`feat/`, `fix/`, `docs/`, `chore/` and a
|
|
21
|
+
slug) cut from an up-to-date `develop` and merged into it by draft pull request with rebase and merge. `main` is what is released: it
|
|
22
|
+
is protected and changes only by a promotion pull request from `develop`, merged with a merge commit (`CONTRIBUTING.md`).
|
|
23
|
+
- **Never commit or push without being asked.** Prepare changes in the working tree and stop. **Never merge a pull request
|
|
24
|
+
automatically.**
|
|
25
|
+
- **Commits explain why, not just what:** `type(scope): summary` (`feat`, `fix`, `docs`, `chore`) under 72 characters, a body wrapped at
|
|
26
|
+
100, a `Verified:` line naming what was run, one logical change each. An agent's commits end with its own model-agnostic trailer:
|
|
27
|
+
`Co-Authored-By: Claude Code <noreply@anthropic.com>` or `Co-Authored-By: Codex <noreply@openai.com>`, never one naming a model (the
|
|
28
|
+
promotion check refuses it).
|
|
29
|
+
- **Pull requests into `develop` are drafts,** marked ready only on instruction; the body says what changed and why and ends with the
|
|
30
|
+
agent's footer.
|
|
31
|
+
- **A version is set with its changelog section,** in the same change: `version` in `package.json` (or, in a repository of several
|
|
32
|
+
components, the file `sovereign.json` names for it) and `## [X.Y.Z] - date` in its changelog, in plain words for someone upgrading. A
|
|
33
|
+
promotion titled `Release` with that version's tag publishes it on merge (`RELEASING.md`).
|
|
34
|
+
- **CI runs only for `main`:** on pull requests into it that are not drafts, before a release and by hand; never for `develop` or a
|
|
35
|
+
feature branch, which the pre-push hook (`npm run verify`) checks locally.
|
|
36
|
+
- **Verify before claiming done,** and show the output. A regression test is trusted only after it has been seen to fail against the code
|
|
37
|
+
it guards.
|
|
38
|
+
- **Docs are part of the change:** a statement a change makes false is fixed in the same change.
|
|
39
|
+
- **Flag Docker-config impact immediately:** a new or renamed environment variable, port, on-disk path or native dependency updates the
|
|
40
|
+
`Dockerfile`, `.dockerignore` and Compose files in the same change.
|
|
41
|
+
- **Shared files are written, not edited:** the files `npm create @sovereignfs app sync` writes (this section among them) are changed
|
|
42
|
+
in the template, in sovereignfs/sovereign, and taken with the next sync; a file this app keeps as its own is listed in `package.json`
|
|
43
|
+
under `sovereign.unmanaged`.
|
|
44
|
+
|
|
45
|
+
<!-- sovereign:shared:end -->
|
|
46
|
+
|
|
47
|
+
## Rules of this app
|
|
48
|
+
|
|
49
|
+
Say here what is particular to this app: its data, its pages, what it must never do.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
What changed in each version of **TITLE**, newest first, in the form of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
|
|
4
|
+
versions follow [semver](https://semver.org/). A version's section is written in the change that sets the version, dated that day, and
|
|
5
|
+
becomes its GitHub release's notes (RELEASING.md).
|
|
6
|
+
|
|
7
|
+
## [0.1.0] - 2026-01-01
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- The app, as `npm create @sovereignfs app` made it.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
Written by `npm create @sovereignfs app sync`; do not edit it here. The conventions for this repository live in [AGENTS.md](AGENTS.md),
|
|
4
|
+
shared by every agent; Claude Code loads it through the import below.
|
|
5
|
+
|
|
6
|
+
@AGENTS.md
|
|
7
|
+
|
|
8
|
+
Claude Code's commit trailer is `Co-Authored-By: Claude Code <noreply@anthropic.com>`: model-agnostic, even if your harness suggests a
|
|
9
|
+
model-specific one.
|
|
@@ -2,7 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
How work gets into `develop`, and from there into `main`. It is the workflow of
|
|
4
4
|
[Sovereign](https://github.com/sovereignfs/sovereign/blob/main/CONTRIBUTING.md) itself, so an app made with
|
|
5
|
-
`npm create @sovereignfs app` is worked on the same way.
|
|
5
|
+
`npm create @sovereignfs app` is worked on the same way. The sections above and below the shared one are this app's own (how to set it
|
|
6
|
+
up, how it is planned); the shared one is written by `npm create @sovereignfs app sync` and is the same in every app of the suite.
|
|
7
|
+
|
|
8
|
+
<!-- sovereign:shared:begin -->
|
|
6
9
|
|
|
7
10
|
## Branches
|
|
8
11
|
|
|
@@ -37,50 +40,61 @@ commit; fix commit messages before they reach `develop`, which is never rewritte
|
|
|
37
40
|
|
|
38
41
|
## Continuous integration
|
|
39
42
|
|
|
40
|
-
CI
|
|
41
|
-
released:
|
|
43
|
+
CI runs only where a change is about to reach what is released:
|
|
42
44
|
|
|
43
45
|
- on a pull request into `main` that is not a draft (the promotion from `develop`); marking a draft ready for review runs it;
|
|
44
|
-
-
|
|
46
|
+
- before each release is published (the publish workflow runs the checks on the tagged commit);
|
|
45
47
|
- by hand, for any branch: **Actions → CI → Run workflow**.
|
|
46
48
|
|
|
47
49
|
It never runs on a push to `develop` or a feature branch, nor on a pull request into `develop`, so runner time is not spent on every
|
|
48
|
-
commit. Those are checked on your machine instead:
|
|
49
|
-
`npm run verify`
|
|
50
|
+
commit. Those are checked on your machine instead: where the repository has versioned hooks in `.githooks/` (an app's `npm install` turns
|
|
51
|
+
them on), the pre-push hook runs its checks (`npm run verify`) before anything is pushed. This is the CI strategy of every repository of
|
|
52
|
+
the suite.
|
|
50
53
|
|
|
51
54
|
## Promoting `develop` into `main`
|
|
52
55
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
`develop` is never rewritten, so it stays an ancestor of `main` and the next pull request shows only what is new.
|
|
58
|
-
4. To publish, tag the merge commit and push the tag, which builds and publishes the image (`.github/workflows/publish.yml`):
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
git switch main && git pull
|
|
62
|
-
git tag vX.Y.Z && git push origin vX.Y.Z
|
|
63
|
-
```
|
|
56
|
+
`main` changes only through a promotion pull request from `develop`, merged with **a merge commit**, the one place a merge commit is
|
|
57
|
+
used; `develop` is never rewritten, so it stays an ancestor of `main` and the next promotion shows only what is new. Its title is the
|
|
58
|
+
version, **`vX.Y.Z`**, or **`Release vX.Y.Z`** when merging it is to publish that version, which [RELEASING.md](RELEASING.md) describes:
|
|
59
|
+
there is no release script, and no tag to push by hand.
|
|
64
60
|
|
|
65
|
-
|
|
66
|
-
|
|
61
|
+
The **Promotion** check, which `main` requires, holds the title to the code, refuses a commit whose agent trailer names a model, and
|
|
62
|
+
fails when a shared file differs from the template (below). Editing the title runs it again.
|
|
67
63
|
|
|
68
64
|
Once the promotion is merged, `.github/workflows/sync-develop.yml` moves `develop` forward to the merge commit. It is a fast-forward,
|
|
69
65
|
never a rewrite (`develop` is already in the merge commit's history), so `develop` is not shown as behind `main` and the release tags are
|
|
70
66
|
in its history. If a commit reached `develop` after the merge, the run leaves `develop` as it is and says so; pull before you start new
|
|
71
67
|
work either way.
|
|
72
68
|
|
|
73
|
-
##
|
|
69
|
+
## Shared files
|
|
74
70
|
|
|
75
|
-
|
|
71
|
+
Some files are the same in every app of the suite and are written, not edited: `.github/workflows/promotion.yml`, `release.yml` and
|
|
72
|
+
`sync-develop.yml`, `.github/repository.json`, `CLAUDE.md`, and the shared sections of this file, `RELEASING.md` and `AGENTS.md`. They come
|
|
73
|
+
from the template of the version of `@sovereignfs/create` that `package.json` pins:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npm create @sovereignfs app sync # write them from the pinned version's template
|
|
77
|
+
npm create @sovereignfs app sync --check # say which differ, and fail; the Promotion check runs this
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
To change one, change it in the template, in [sovereignfs/sovereign](https://github.com/sovereignfs/sovereign), and take it here by moving
|
|
81
|
+
the pin and running `sync`. A file this app keeps as its own is listed in `package.json` under `sovereign.unmanaged`, by its path from the
|
|
82
|
+
repository's root, and the check then leaves it alone.
|
|
83
|
+
|
|
84
|
+
## Repository settings
|
|
85
|
+
|
|
86
|
+
The repository's merge settings and its rulesets (what `main` and `develop` allow, and the checks `main` requires) are code, in
|
|
87
|
+
`.github/repository.json`, and are never set in GitHub's interface. Once the repository is on GitHub, push both branches and apply them,
|
|
88
|
+
signed in with `gh` as an owner of the repository:
|
|
76
89
|
|
|
77
90
|
```bash
|
|
78
91
|
git push -u origin main develop
|
|
92
|
+
npm create @sovereignfs app settings apply # make GitHub match .github/repository.json
|
|
93
|
+
npm create @sovereignfs app settings check # say what differs, and fail
|
|
79
94
|
```
|
|
80
95
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
description, so the merge commit reads `vX.Y.Z` or `Release vX.Y.Z`.
|
|
96
|
+
`main` takes changes only by pull request, merged with a merge commit, and requires the Promotion check and the checks under
|
|
97
|
+
`sovereign.requiredChecks` in `package.json` (`requiredChecks` in `sovereign.json` for a repository of several components); `develop` can never be deleted or force-pushed, so merging a promotion (which would
|
|
98
|
+
otherwise delete its head branch) leaves it in place. A change to the settings is a commit like any other, applied after it lands.
|
|
99
|
+
|
|
100
|
+
<!-- sovereign:shared:end -->
|
package/template/app/README.md
CHANGED
|
@@ -12,6 +12,10 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
|
|
|
12
12
|
| `Dockerfile` | One image, not root, on the manifest's port. Its label and port are made from the manifest when it is built |
|
|
13
13
|
| `.github/workflows/publish.yml` | On a `vX.Y.Z` tag of a commit on `main`, builds the image for amd64 and arm64 and publishes it to `ghcr.io/<owner>/<repository>` |
|
|
14
14
|
| `CONTRIBUTING.md` | How work lands on `develop` and is released to `main` (below) |
|
|
15
|
+
| `RELEASING.md`, `CHANGELOG.md` | How a version is released (a promotion titled `Release vX.Y.Z`), and each version's notes |
|
|
16
|
+
| `AGENTS.md`, `CLAUDE.md` | The conventions for agents: the app's own sections, and one shared by every app of the suite |
|
|
17
|
+
| `.github/repository.json` | The repository's merge settings and rulesets, as code (`npm create @sovereignfs app settings apply`) |
|
|
18
|
+
| `.github/workflows/promotion.yml`, `release.yml` | The promotion check and the release on merge, which call the workflows every app shares |
|
|
15
19
|
| `.github/workflows/ci.yml`, `.githooks/pre-push` | The checks: CI for pull requests into `main` and release tags only, the pre-push hook for everything else |
|
|
16
20
|
| `.github/workflows/sync-develop.yml` | After a promotion into `main` is merged, fast-forwards `develop` to the merge commit |
|
|
17
21
|
| `app/auth/[action]/route.ts` | Sign-in, sign-out, core's back-channel logout, and core's notice that a person deleted their account |
|
|
@@ -26,7 +30,7 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
|
|
|
26
30
|
|
|
27
31
|
Work lands on `develop`, committed directly or merged from a feature branch; `main` is what is released, protected, and changed only by a
|
|
28
32
|
pull request from `develop` titled with its version, merged with a merge commit, which is tagged `vX.Y.Z` when that version is published. `npm create @sovereignfs app`
|
|
29
|
-
made both branches and left you on `develop`. [CONTRIBUTING.md](CONTRIBUTING.md) has the whole workflow,
|
|
33
|
+
made both branches and left you on `develop`. [CONTRIBUTING.md](CONTRIBUTING.md) has the whole workflow, the shared files `npm create @sovereignfs app sync` keeps, and how `main` is protected on
|
|
30
34
|
GitHub.
|
|
31
35
|
|
|
32
36
|
## Build and host it
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Releasing **TITLE**
|
|
2
|
+
|
|
3
|
+
The sections above and below the shared one are this repository's own (what is particular to how it publishes); the shared one is
|
|
4
|
+
written by `npm create @sovereignfs app sync` and is the same in every repository of the suite.
|
|
5
|
+
|
|
6
|
+
<!-- sovereign:shared:begin -->
|
|
7
|
+
|
|
8
|
+
A release is a promotion of `develop` into `main` that says it is one. There is no release script to run.
|
|
9
|
+
|
|
10
|
+
1. **Set the version and its changelog section on `develop`,** in the change that makes them: `version` in `package.json` (semver: a
|
|
11
|
+
fix is a patch, a feature a minor, a break a major) and a section `## [X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md`, saying in plain words
|
|
12
|
+
what changed for someone upgrading. The section is the release's notes; a promotion titled `Release` is refused without it.
|
|
13
|
+
2. **Open the promotion pull request** from `develop` into `main`, titled **`vX.Y.Z`**, or **`Release vX.Y.Z`** when merging it is to
|
|
14
|
+
publish that version. The **Promotion** check holds the title to the code: the version must be the one in `package.json`, and a
|
|
15
|
+
`Release` title must name a version not tagged yet, with its changelog section. Editing the title runs it again.
|
|
16
|
+
3. **Merge it with a merge commit** (the only method `main` allows). For a `Release` title, the **Release** workflow checks the title
|
|
17
|
+
against the merged code, tags the merge commit `vX.Y.Z`, and calls `.github/workflows/publish.yml`, which runs the app's checks,
|
|
18
|
+
publishes the image to `ghcr.io/<owner>/<repository>:X.Y.Z` and makes the GitHub release from the changelog section.
|
|
19
|
+
|
|
20
|
+
A version promoted without `Release` can be published later by pushing its tag on the merge commit that brought it:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
git switch main && git pull
|
|
24
|
+
git tag vX.Y.Z <merge commit> && git push origin vX.Y.Z
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The promotion check and the release are workflows every app of the suite shares, kept in
|
|
28
|
+
[sovereignfs/sovereign](https://github.com/sovereignfs/sovereign/tree/main/.github/workflows) and run with the version of
|
|
29
|
+
`@sovereignfs/create` this app pins in `package.json`.
|
|
30
|
+
|
|
31
|
+
<!-- sovereign:shared:end -->
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
{
|
|
2
|
+
"settings": {
|
|
3
|
+
"default_branch": "main",
|
|
4
|
+
"allow_merge_commit": true,
|
|
5
|
+
"allow_rebase_merge": true,
|
|
6
|
+
"allow_squash_merge": false,
|
|
7
|
+
"merge_commit_title": "PR_TITLE",
|
|
8
|
+
"merge_commit_message": "PR_BODY",
|
|
9
|
+
"delete_branch_on_merge": true
|
|
10
|
+
},
|
|
11
|
+
"rulesets": [
|
|
12
|
+
{
|
|
13
|
+
"name": "main is released through promotion pull requests",
|
|
14
|
+
"target": "branch",
|
|
15
|
+
"enforcement": "active",
|
|
16
|
+
"conditions": { "ref_name": { "include": ["refs/heads/main"], "exclude": [] } },
|
|
17
|
+
"bypass_actors": [{ "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" }],
|
|
18
|
+
"rules": [
|
|
19
|
+
{ "type": "deletion" },
|
|
20
|
+
{ "type": "non_fast_forward" },
|
|
21
|
+
{
|
|
22
|
+
"type": "pull_request",
|
|
23
|
+
"parameters": {
|
|
24
|
+
"required_approving_review_count": 0,
|
|
25
|
+
"dismiss_stale_reviews_on_push": false,
|
|
26
|
+
"require_code_owner_review": false,
|
|
27
|
+
"require_last_push_approval": false,
|
|
28
|
+
"required_review_thread_resolution": false,
|
|
29
|
+
"allowed_merge_methods": ["merge"]
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"type": "required_status_checks",
|
|
34
|
+
"parameters": {
|
|
35
|
+
"strict_required_status_checks_policy": false,
|
|
36
|
+
"required_status_checks": [{ "context": "Promotion / Promotion title" }]
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
]
|
|
40
|
+
},
|
|
41
|
+
{
|
|
42
|
+
"name": "develop is never deleted or rewritten",
|
|
43
|
+
"target": "branch",
|
|
44
|
+
"enforcement": "active",
|
|
45
|
+
"conditions": { "ref_name": { "include": ["refs/heads/develop"], "exclude": [] } },
|
|
46
|
+
"bypass_actors": [],
|
|
47
|
+
"rules": [{ "type": "deletion" }, { "type": "non_fast_forward" }]
|
|
48
|
+
}
|
|
49
|
+
]
|
|
50
|
+
}
|
|
@@ -11,10 +11,16 @@ on:
|
|
|
11
11
|
types: [opened, synchronize, reopened, ready_for_review]
|
|
12
12
|
workflow_dispatch:
|
|
13
13
|
workflow_call:
|
|
14
|
+
inputs:
|
|
15
|
+
ref:
|
|
16
|
+
description: The tag to check, when publish.yml is called for a release; empty for what triggered the run.
|
|
17
|
+
type: string
|
|
18
|
+
required: false
|
|
19
|
+
default: ''
|
|
14
20
|
|
|
15
21
|
concurrency:
|
|
16
|
-
group: ci-${{ github.event.pull_request.number || github.sha }}
|
|
17
|
-
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
|
|
22
|
+
group: ci-${{ inputs.ref || github.event.pull_request.number || github.sha }}
|
|
23
|
+
cancel-in-progress: ${{ github.event_name == 'pull_request' && inputs.ref == '' }}
|
|
18
24
|
|
|
19
25
|
permissions:
|
|
20
26
|
contents: read
|
|
@@ -25,11 +31,13 @@ jobs:
|
|
|
25
31
|
runs-on: ubuntu-latest
|
|
26
32
|
timeout-minutes: 20
|
|
27
33
|
# A draft pull request runs nothing; marking it ready for review runs it.
|
|
28
|
-
|
|
34
|
+
# A release run (`ref` given) always runs.
|
|
35
|
+
if: inputs.ref != '' || github.event_name != 'pull_request' || github.event.pull_request.draft == false
|
|
29
36
|
steps:
|
|
30
37
|
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
31
38
|
with:
|
|
32
39
|
persist-credentials: false
|
|
40
|
+
ref: ${{ inputs.ref }}
|
|
33
41
|
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
34
42
|
with:
|
|
35
43
|
node-version: 24
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: Promotion
|
|
2
|
+
|
|
3
|
+
# Written by `npm create @sovereignfs sync`; do not edit it here (CONTRIBUTING.md, "Shared files"). Checks a promotion pull request
|
|
4
|
+
# (develop -> main) with the workflow every app of the suite shares: its title names this app's version, its commits carry only the agent
|
|
5
|
+
# trailers allowed, and the shared files are the template's. `main` requires this check (.github/repository.json).
|
|
6
|
+
on:
|
|
7
|
+
pull_request:
|
|
8
|
+
branches: [main]
|
|
9
|
+
types: [opened, edited, synchronize, reopened, ready_for_review]
|
|
10
|
+
|
|
11
|
+
permissions:
|
|
12
|
+
contents: read
|
|
13
|
+
|
|
14
|
+
concurrency:
|
|
15
|
+
group: promotion-${{ github.event.pull_request.number }}
|
|
16
|
+
cancel-in-progress: true
|
|
17
|
+
|
|
18
|
+
jobs:
|
|
19
|
+
promotion:
|
|
20
|
+
name: Promotion
|
|
21
|
+
uses: sovereignfs/sovereign/.github/workflows/app-promotion.yml@__WORKFLOWS_REF__
|
|
22
|
+
with:
|
|
23
|
+
directory: '__DIRECTORY__'
|
|
24
|
+
tag-prefix: '__TAG_PREFIX__'
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
name: Publish
|
|
2
2
|
|
|
3
|
-
# Builds this app's image
|
|
4
|
-
#
|
|
3
|
+
# Builds this app's image and publishes it to GitHub's container registry as ghcr.io/<owner>/<repository> tagged X.Y.Z, which is where
|
|
4
|
+
# `sv app add --git` looks for it (operator-cli §4.2.1), then makes the version's GitHub release from its CHANGELOG.md section. The
|
|
5
|
+
# release workflow (release.yml) calls it with the tag when a promotion titled `Release vX.Y.Z` is merged (RELEASING.md); a tag pushed by
|
|
6
|
+
# hand starts it too:
|
|
5
7
|
#
|
|
6
8
|
# git tag v1.0.0 && git push origin v1.0.0
|
|
7
9
|
#
|
|
8
|
-
# Nothing is published unless the checks in ci.yml pass on the tagged commit
|
|
10
|
+
# Nothing is published unless the checks in ci.yml pass on the tagged commit, that commit is on `main`, and the version has a changelog
|
|
11
|
+
# section.
|
|
9
12
|
#
|
|
10
13
|
# The image carries the manifest as its label and is built to listen on the manifest's port, both made from sovereign.manifest.json by
|
|
11
14
|
# @sovereignfs/manifest, so the manifest is written once.
|
|
@@ -13,31 +16,44 @@ on:
|
|
|
13
16
|
push:
|
|
14
17
|
tags:
|
|
15
18
|
- 'v*.*.*'
|
|
19
|
+
workflow_call:
|
|
20
|
+
inputs:
|
|
21
|
+
tag:
|
|
22
|
+
description: The tag to publish, such as v1.2.0; it exists already, on the promotion's merge commit.
|
|
23
|
+
type: string
|
|
24
|
+
required: true
|
|
16
25
|
|
|
17
26
|
permissions:
|
|
18
27
|
contents: read
|
|
19
|
-
packages: write
|
|
20
28
|
|
|
21
29
|
jobs:
|
|
22
30
|
# The app's checks (ci.yml) on the tagged commit, before anything is built or published.
|
|
23
31
|
validate:
|
|
24
32
|
uses: ./.github/workflows/ci.yml
|
|
33
|
+
with:
|
|
34
|
+
ref: ${{ inputs.tag }}
|
|
25
35
|
|
|
26
36
|
image:
|
|
27
37
|
needs: validate
|
|
28
38
|
runs-on: ubuntu-latest
|
|
39
|
+
permissions:
|
|
40
|
+
contents: read
|
|
41
|
+
packages: write
|
|
42
|
+
outputs:
|
|
43
|
+
version: ${{ steps.version.outputs.version }}
|
|
29
44
|
steps:
|
|
30
45
|
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
31
46
|
with:
|
|
32
47
|
persist-credentials: false
|
|
33
48
|
fetch-depth: 0
|
|
49
|
+
ref: ${{ inputs.tag }}
|
|
34
50
|
|
|
35
51
|
# A release is the merge commit of a pull request from `develop` into `main` (CONTRIBUTING.md), never a commit of `develop` or of a
|
|
36
52
|
# branch that was tagged by mistake.
|
|
37
53
|
- name: Check the tagged commit is on main
|
|
38
54
|
run: |
|
|
39
55
|
git fetch --no-tags origin main
|
|
40
|
-
if ! git merge-base --is-ancestor
|
|
56
|
+
if ! git merge-base --is-ancestor HEAD origin/main; then
|
|
41
57
|
echo "The tagged commit is not on main; refusing to publish." >&2
|
|
42
58
|
exit 1
|
|
43
59
|
fi
|
|
@@ -49,15 +65,22 @@ jobs:
|
|
|
49
65
|
|
|
50
66
|
# The tag names the version, so it has to be the one the package says. The image is tagged X.Y.Z, without the v.
|
|
51
67
|
- id: version
|
|
68
|
+
env:
|
|
69
|
+
TAG: ${{ inputs.tag || github.ref_name }}
|
|
52
70
|
run: |
|
|
53
|
-
expected="${
|
|
71
|
+
expected="${TAG#v}"
|
|
54
72
|
actual="$(node -p "require('./package.json').version")"
|
|
55
73
|
if [ "$actual" != "$expected" ]; then
|
|
56
|
-
echo "The tag $
|
|
74
|
+
echo "The tag $TAG expects version $expected, but package.json says $actual." >&2
|
|
57
75
|
exit 1
|
|
58
76
|
fi
|
|
59
77
|
echo "version=$expected" >> "$GITHUB_OUTPUT"
|
|
60
78
|
|
|
79
|
+
# The release notes are the version's CHANGELOG.md section (RELEASING.md); a version without one is not published.
|
|
80
|
+
- run: npx create app release notes "$TAG" > /dev/null
|
|
81
|
+
env:
|
|
82
|
+
TAG: ${{ inputs.tag || github.ref_name }}
|
|
83
|
+
|
|
61
84
|
# Fails the build on a manifest an instance would refuse.
|
|
62
85
|
- run: npx sovereign-manifest check
|
|
63
86
|
|
|
@@ -82,3 +105,29 @@ jobs:
|
|
|
82
105
|
tags: ${{ steps.image.outputs.name }}:${{ steps.version.outputs.version }}
|
|
83
106
|
labels: ${{ steps.manifest.outputs.labels }}
|
|
84
107
|
build-args: ${{ steps.manifest.outputs.build-args }}
|
|
108
|
+
|
|
109
|
+
# The GitHub release for the tag, with the version's CHANGELOG.md section as its notes. Run again, it replaces the notes.
|
|
110
|
+
release:
|
|
111
|
+
needs: image
|
|
112
|
+
runs-on: ubuntu-latest
|
|
113
|
+
permissions:
|
|
114
|
+
contents: write
|
|
115
|
+
steps:
|
|
116
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
117
|
+
with:
|
|
118
|
+
persist-credentials: false
|
|
119
|
+
ref: ${{ inputs.tag }}
|
|
120
|
+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
121
|
+
with:
|
|
122
|
+
node-version: 24
|
|
123
|
+
- run: npm ci --ignore-scripts --no-audit --no-fund
|
|
124
|
+
- env:
|
|
125
|
+
GH_TOKEN: ${{ github.token }}
|
|
126
|
+
TAG: ${{ inputs.tag || github.ref_name }}
|
|
127
|
+
run: |
|
|
128
|
+
npx create app release notes "$TAG" > notes.md
|
|
129
|
+
if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
|
|
130
|
+
gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --notes-file notes.md
|
|
131
|
+
else
|
|
132
|
+
gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag --title "$TAG" --notes-file notes.md
|
|
133
|
+
fi
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
# Written by `npm create @sovereignfs sync`; do not edit it here (CONTRIBUTING.md, "Shared files"). When a promotion pull request titled
|
|
4
|
+
# `Release vX.Y.Z` is merged, the workflow every app of the suite shares checks the title against the merged code and tags the merge
|
|
5
|
+
# commit; this app's own publish workflow then builds and publishes that tag (RELEASING.md). A title without `Release` publishes nothing.
|
|
6
|
+
on:
|
|
7
|
+
pull_request:
|
|
8
|
+
branches: [main]
|
|
9
|
+
types: [closed]
|
|
10
|
+
|
|
11
|
+
permissions:
|
|
12
|
+
contents: read
|
|
13
|
+
|
|
14
|
+
concurrency:
|
|
15
|
+
group: release-${{ github.event.pull_request.number }}
|
|
16
|
+
cancel-in-progress: false
|
|
17
|
+
|
|
18
|
+
jobs:
|
|
19
|
+
plan:
|
|
20
|
+
name: Plan
|
|
21
|
+
permissions:
|
|
22
|
+
contents: write
|
|
23
|
+
uses: sovereignfs/sovereign/.github/workflows/app-release.yml@__WORKFLOWS_REF__
|
|
24
|
+
with:
|
|
25
|
+
directory: '__DIRECTORY__'
|
|
26
|
+
tag-prefix: '__TAG_PREFIX__'
|
|
27
|
+
|
|
28
|
+
publish:
|
|
29
|
+
name: Publish
|
|
30
|
+
needs: plan
|
|
31
|
+
if: needs.plan.outputs.tag != ''
|
|
32
|
+
permissions:
|
|
33
|
+
contents: write
|
|
34
|
+
packages: write
|
|
35
|
+
id-token: write
|
|
36
|
+
attestations: write
|
|
37
|
+
uses: ./.github/workflows/publish.yml
|
|
38
|
+
with:
|
|
39
|
+
tag: ${{ needs.plan.outputs.tag }}
|
|
40
|
+
secrets: inherit
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Releasing **TITLE**
|
|
2
|
+
|
|
3
|
+
The sections above and below the shared one are this repository's own (what is particular to how it publishes); the shared one is
|
|
4
|
+
written by `npm create @sovereignfs app sync` and is the same in every repository of the suite.
|
|
5
|
+
|
|
6
|
+
<!-- sovereign:shared:begin -->
|
|
7
|
+
|
|
8
|
+
This repository releases several components, each with its own version, tag and changelog, listed in `sovereign.json`. A release is a
|
|
9
|
+
promotion of `develop` into `main` that says which of them it publishes. There is no release script.
|
|
10
|
+
|
|
11
|
+
1. **Set each component's version and its changelog section on `develop`,** in the change that makes them: the version in the file
|
|
12
|
+
`sovereign.json` names for it (semver: a fix is a patch, a feature a minor, a break a major), and a section `## [X.Y.Z] - YYYY-MM-DD`
|
|
13
|
+
in its changelog, saying in plain words what changed for someone upgrading. The section is the release's notes.
|
|
14
|
+
2. **Open the promotion pull request** from `develop` into `main`, titled with the versions it carries, by their tags (each component's tag
|
|
15
|
+
prefix, then `vX.Y.Z`, such as `web-v1.2.0`), and starting with **`Release`** when merging it is to publish them:
|
|
16
|
+
`Release web-v1.2.0, cli-v0.6.0`. The **Promotion** check holds the title to the code: each version must be its component's current
|
|
17
|
+
one, and under `Release` not tagged yet, with its changelog section. Editing the title runs it again.
|
|
18
|
+
3. **Merge it with a merge commit** (the only method `main` allows). For a `Release` title, the **Release** workflow checks the title
|
|
19
|
+
against the merged code, tags the merge commit with each version, and calls each component's publish workflow with its tag.
|
|
20
|
+
|
|
21
|
+
A version promoted without `Release` can be published later by pushing its tag on the merge commit that brought it.
|
|
22
|
+
|
|
23
|
+
The promotion check and the release are workflows every repository of the suite shares, kept in
|
|
24
|
+
[sovereignfs/sovereign](https://github.com/sovereignfs/sovereign/tree/main/.github/workflows) and run with the version of
|
|
25
|
+
`@sovereignfs/create` that `sovereign.json` pins.
|
|
26
|
+
|
|
27
|
+
<!-- sovereign:shared:end -->
|