docs: align release and recovery guidance
This commit is contained in:
NuklearRabbit
+4
-2
@@ -52,6 +52,7 @@ a17f95d96d3c9fbc69d870874e6fbb7472091adefc454b24f835db1279511d72 8296
|
||||
72e846f591c47a0291e7466e58e052d3d5afcf551c4e6c848632ac3c552a1244 3043 docs/CURRENT_STATE.md
|
||||
30a92bcf5daadb019efa2f82cb820ea302490dd1d68fb772674dc3faccd3e594 2045 docs/DEPLOYMENT_SETUP.md
|
||||
eb42f979666e05d51c587e4223282914926a2b9b1ade9f3fb75525019ce7f738 4616 docs/DIAGNOSTICS.md
|
||||
1d8aa3c688a9d330b9a5303b09e9e3049c50bf04f97807c7ff659607baa34c32 1464 docs/ERROR_CODES.md
|
||||
a0cd06a96f23a94e118feb012be0fa1ac51345951cb2ba8e67fb8c889c4c342a 5007 docs/LUMAOPS_SERVER_AUDIT.md
|
||||
648dd6bca6b45668fb86eb3e1f6c5898dd8da0291b990f1bb5105cfd79421343 1301 docs/MUTATION_MODEL.md
|
||||
f79908fb3dad98c38030c6e6be7c79a1999e0478ed9c2496923891954438daa1 4581 docs/RELEASE_AUDIT_0.6.0.md
|
||||
@@ -90,6 +91,7 @@ ed40e08bac8792f95970bc05e49bce3cc9e288a08d11565a1bd156d787360a3b 720
|
||||
25169225d73d22b9d884ab3b5c1625f03fd44e53c7a7a4c4067775e80482c9f8 2182 docs/RELEASE_NOTES_0.9.3.md
|
||||
720506842e0aeb30c9fc635f86a52a5545556f092e678cf37f08436243244c3d 933 docs/RELEASE_NOTES_0.9.4.md
|
||||
dd90c81a375f97dfb7fa8f7808db03b19d7e7dafe3818a93537397f57eaae829 2109 docs/RELEASE_NOTES_0.9.5.md
|
||||
ed9af435be5986cc597f75d8de89cd51dd4cc8860c8fcbb4cd8eafdd4438857a 1364 docs/RELEASING.md
|
||||
2b631b9d6d973bdd70869d84886ff339da351e29e17598970b3b27915674661d 4175 docs/ROADMAP.md
|
||||
1ccde232c060395d7aedce27e89a7647b77afe28ab71de0a5a3efeded57369d3 140415 docs/screenshots/deploy-confirmation.png
|
||||
b39506254ffa2c73c389fb4795b3a745368bbeb7d8514cc47a636316d6d9a6aa 107166 docs/screenshots/deployment-run.png
|
||||
@@ -103,7 +105,7 @@ c8a5e80bb9fd2d442d2d23d30e6ac1528cf2330e6e19492b7c6799e2d1508b53 112868
|
||||
2fd71e9bcaeb4cb10c3fa2496b7e52fedf70c5b7f871cd587e22dc060c399079 4421 docs/SSH_UNRAID_DEPLOYMENT.md
|
||||
b6a178215dab054006aae4944b8ffcbe7f6100691c30f08e221e3a2dbff4cd42 2147 docs/STATUS_ENDPOINT.md
|
||||
0adfeabb98168a7fc0b02bae8d4af436d3c59459012fb05b2216e02265190128 3139 docs/STITCH_REVIEW.md
|
||||
4625a10ebd3c749f60b2a7bef6b1716cd05dbc44ccceba0491a1b46bc293c195 4883 docs/TEST_MATRIX.md
|
||||
bcfef2c5a180e3665df3c08517d5251339682ca5bcc90e4681b5bbf4f9c7ba55 6296 docs/TEST_MATRIX.md
|
||||
dbbd9fa96988e7543e98c85da864adaadd3057815f18d20a3b3ccb5c540a169d 4558 docs/UPDATING.md
|
||||
4bffda594058697345569d937d7a524f094ac85a0f338f0ef18fcf3f94d8c299 1292 eslint.config.js
|
||||
c230b931abf2293d2d44b7a69b94c35f1142c093cc46b88739a0de5cbd6d1896 1532 examples/gitea-actions/deploy.yml
|
||||
@@ -117,7 +119,7 @@ c230b931abf2293d2d44b7a69b94c35f1142c093cc46b88739a0de5cbd6d1896 1532
|
||||
3b16a087c73b600415394dff8b8e34e7f7519e48fde1cf443007b2e11ca77b27 13123 main.cjs
|
||||
91a984a89dd57a084b9a2331763cacdb061582fb590f13df379d92c1a77a2ee1 352 OVERLAY-INSTRUCTIONS.md
|
||||
f3e2a262e251eb165f342dc3c184625ec10d56e536b5a987199b9944f463eee9 181069 package-lock.json
|
||||
0692366144cd9e941aeda32757521ae38ff98cf017adbad66e974178d8855c52 4761 package.json
|
||||
48e25abda43f5463c5c4631f5a29f7e9b2e744383a23489b4e54dedf38c74940 4817 package.json
|
||||
82865e814a82628b778c53ec83bcda26bf1109d8bb14c11208530089f4dc96db 10522 preload.cjs
|
||||
abe5dd6fd68f2970cd19ef134094907c67219061d8fe9a1a08324c78de4ad437 484 PUBLISH-AND-ENABLE-UPDATE.cmd
|
||||
f018383f755352ca448e2ebb1e19b1dba412a3eb793d61e64b02953e300754fd 10538 Publish-ForgeFlow-Release.ps1
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# ForgeFlow error and recovery catalog
|
||||
|
||||
| Code | Meaning | Recovery |
|
||||
| --- | --- | --- |
|
||||
| `RECONCILIATION_PLAN_REQUIRED` | A server mutation was requested without its reviewed plan. | Open Review reconciliation and apply the current plan ID. |
|
||||
| `RECONCILIATION_PLAN_STALE` | Server truth changed after preview. | Rescan, review the new impact and apply that plan. |
|
||||
| `SERVER_GIT_VERIFICATION_FAILED` | Branch, deploy key or pinned SSH evidence could not be proven. | Run Verify server pull; repair only the failing check before retrying. |
|
||||
| `DEPLOY_KEY_NOT_READ_ONLY` | A matching key can write to Gitea. | Revoke it in Gitea and configure a dedicated read-only key. |
|
||||
| `SSH_DEPLOYMENT_PREFLIGHT_FAILED` | One or more deployment safety checks failed. | Open preflight evidence and follow the failing check's detail. |
|
||||
| `REMOTE_WRITE_ACCESS_REQUIRED` | The SSH user cannot safely write the managed source/state paths. | Use Check / fix write access after reviewing its scoped impact. |
|
||||
| `UPDATE_ORIGIN_MISMATCH` | An update asset points outside the trusted Gitea origin. | Correct release asset URLs; never bypass the origin check. |
|
||||
| `UPDATE_CHECKSUM_MISMATCH` | Downloaded bytes do not match the published checksum. | Keep the current version and republish the exact commit atomically. |
|
||||
|
||||
Audit and discovery never repair these conditions automatically. Mutating recovery
|
||||
actions require an explicit user flow and preserve rollback or snapshot evidence.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Releasing ForgeFlow
|
||||
|
||||
ForgeFlow releases are built only from a clean, reviewed commit on Node 22 LTS.
|
||||
|
||||
## Quality gate
|
||||
|
||||
```powershell
|
||||
npm ci
|
||||
npm run quality
|
||||
npm audit --omit=dev --audit-level=high
|
||||
```
|
||||
|
||||
## Signed Windows build
|
||||
|
||||
Production signing is fail-closed. Configure electron-builder's Authenticode
|
||||
certificate through its supported CSC environment variables, then set:
|
||||
|
||||
```powershell
|
||||
$env:FORGEFLOW_SIGNED_RELEASE = '1'
|
||||
$env:FORGEFLOW_EXPECTED_PUBLISHER = 'exact certificate subject fragment'
|
||||
npm run dist:win
|
||||
```
|
||||
|
||||
Both installer and portable executable must have a valid Authenticode signature,
|
||||
the expected publisher and a timestamp. The build also creates SHA-256 files, a
|
||||
CycloneDX SBOM and a provenance document containing commit and build ID.
|
||||
|
||||
Without `FORGEFLOW_SIGNED_RELEASE=1`, local builds may be unsigned for development
|
||||
testing but must never be published as production releases.
|
||||
|
||||
## Atomic publication
|
||||
|
||||
`npm run release:binary` keeps the Gitea release in draft state while uploading
|
||||
the installer, portable executable, two checksums, provenance and SBOM. It only
|
||||
publishes after all six assets are present. A failed upload leaves a draft rather
|
||||
than exposing an incomplete updater target.
|
||||
|
||||
The production Authenticode certificate and legal publisher identity are
|
||||
`PENDING_HUMAN_INPUT`; all surrounding build and verification code is complete.
|
||||
+27
-2
@@ -1,8 +1,33 @@
|
||||
# Test matrix
|
||||
|
||||
## Automated in v0.4.0
|
||||
## Automated baseline (0.10.x)
|
||||
|
||||
The suite contains 59 passing tests.
|
||||
The quality chain contains 159 automated tests. The latest Windows run completed
|
||||
with 158 passing tests, no failures and one Bash-dependent skip. `npm run
|
||||
coverage` enforces 55% lines/statements/functions and 45% branches; the measured
|
||||
baseline is 68.06% statements/lines, 67.75% functions and 50.27% branches.
|
||||
|
||||
`npm run quality` is the local equivalent of `.gitea/workflows/quality.yml` and
|
||||
runs source verification, ESLint, the complete suite and coverage on Node 22 LTS.
|
||||
Production dependencies are separately checked with `npm audit --omit=dev
|
||||
--audit-level=high`.
|
||||
|
||||
### Server safety and reconciliation
|
||||
|
||||
- inventory discovery is read-only and byte-stable for configuration;
|
||||
- reconciliation requires a content-addressed preview plan and recovery snapshot;
|
||||
- automatic linking requires unique exact provenance/runtime identity;
|
||||
- server-pull verification checks Gitea branch, read-only deploy-key ID, pinned
|
||||
host/key fingerprints, remote/live SHA, Compose evidence, runtime and health;
|
||||
- a fresh access verification is mandatory immediately before server-pull deploy;
|
||||
- writable or missing deploy keys fail closed.
|
||||
|
||||
### Renderer regression matrix
|
||||
|
||||
The dark demo was verified at 1120×720, 1440×900 and 1920×1080. Automated DOM
|
||||
checks cover literal invalid values, unnamed buttons, unlinked field labels,
|
||||
horizontal overflow and modal/palette viewport overflow. Motion-safe illustration
|
||||
contracts and reduced-motion CSS are source-tested.
|
||||
|
||||
### Git and repository behavior
|
||||
|
||||
|
||||
@@ -101,6 +101,8 @@
|
||||
"docs/RELEASE_NOTES_0.10.0.md",
|
||||
"docs/CURRENT_STATE.md",
|
||||
"docs/MUTATION_MODEL.md"
|
||||
,"docs/RELEASING.md"
|
||||
,"docs/ERROR_CODES.md"
|
||||
],
|
||||
"asarUnpack": [
|
||||
"scripts/apply-binary-update.ps1"
|
||||
|
||||
Reference in New Issue
Block a user