docs: simplify v2 release checklist
This commit is contained in:
ajnart committed
1 parent
1b00dfafc6
commit
d1bc97ed3d
1 file changed
+177
-787
+177
-787
@@ -1,801 +1,191 @@
|
||||
# Homarr v2 GA release checklist
|
||||
|
||||
Initial full audit: 2026-09-06 12:30 CEST (Europe/Berlin)
|
||||
Updated: 2026-09-06 17:46 CEST (Europe/Berlin)
|
||||
|
||||
Merge batch updated: 2026-09-06 15:41 CEST (Europe/Berlin)
|
||||
This is the operational go/no-go checklist for releasing Homarr v2 to all users. Validate it against one frozen
|
||||
candidate SHA. Add the run, artifact, screenshot, issue, or written risk acceptance beside every completed gate.
|
||||
|
||||
This is the working go/no-go checklist for the full Homarr v2 release. Do not mark an item complete from an old
|
||||
preview, PR run, or verbal confirmation. Add the final SHA, run URL, screenshot, issue, or written risk acceptance next
|
||||
to every completed release gate.
|
||||
## Current state
|
||||
|
||||
- [x] `origin/release/v2`: `f1c898efe2da2fd55b26e2a674d7f67420acefee`
|
||||
- [x] `origin/dev`: `da32acb4f0ba9d8fa8e9667f56a54f85ca497865`
|
||||
- [x] `origin/main`: `331925c197ad9cbf0138dbbcee9d8952ef9298dc` (`v1.76.2`)
|
||||
- [x] Readiness PRs #6770 and #6772 through #6789 are merged into `release/v2`.
|
||||
- [x] PR #6771 was closed without merging.
|
||||
- [ ] Decide whether PR #6765, the external llama.cpp integration and widget, is included or deferred.
|
||||
- [ ] Review and merge or close PR #6790, the final release-article follow-up.
|
||||
- [ ] Create the `release/v2 -> dev` promotion PR. None is open at this snapshot.
|
||||
- [ ] Create the final `dev -> main` PR. None is open at this snapshot.
|
||||
- [ ] Resolve the current `dev...release/v2` divergence: 54 commits exist only on `dev`, 581 only on `release/v2`,
|
||||
and a dry merge reports 43 conflict paths.
|
||||
- [ ] Nominate the final candidate SHA. Candidate-dependent validation has not yet been run on the final integrated
|
||||
result.
|
||||
|
||||
Refresh these facts at the start of the release window. If the candidate SHA changes, invalidate build, migration,
|
||||
image, browser, security, and deployment sign-offs.
|
||||
|
||||
## Release path
|
||||
|
||||
```text
|
||||
release/v2
|
||||
-> reviewed integration branch based on current dev
|
||||
-> promotion PR into dev
|
||||
-> release/v2 -> dev promotion PR
|
||||
-> final candidate validation on dev
|
||||
-> weekly or manually-created dev -> main PR
|
||||
-> HUMAN merge for the v2 major release
|
||||
-> dev -> main PR
|
||||
-> HUMAN merge for the major release
|
||||
-> Semantic Release creates v2.0.0
|
||||
-> GitHub release + GHCR images + release archives
|
||||
-> docs, Workshop, Discord and support follow-through
|
||||
-> images, archives, docs, Workshop, Discord, and support follow-through
|
||||
```
|
||||
|
||||
The weekly workflow deliberately does not auto-merge major releases. The v2 `dev -> main` PR must be merged by a
|
||||
human after the final go/no-go approval.
|
||||
|
||||
## How to use this checklist
|
||||
|
||||
- `[ ]` means unverified or incomplete.
|
||||
- `[x]` in the audited snapshot means it was observed on the dated snapshot only. Repeat final-candidate gates after
|
||||
integrating into `dev`.
|
||||
- `BLOCKER` must be closed or have explicit written acceptance from the release owner before the production merge.
|
||||
- Put evidence directly below the item or link it from the sign-off record.
|
||||
- If the candidate SHA changes, invalidate build, migration, image, browser, security and deployment sign-offs.
|
||||
|
||||
## Audited snapshot
|
||||
|
||||
These facts are time-sensitive and must be refreshed at the start of the release window.
|
||||
|
||||
- [x] `origin/release/v2`: `35155b18b97b6904f6b571c93de9102c3d79e4da`
|
||||
- [x] `origin/dev`: `da32acb4f0ba9d8fa8e9667f56a54f85ca497865`
|
||||
- [x] `origin/main`: `331925c197ad9cbf0138dbbcee9d8952ef9298dc` (`v1.76.2`)
|
||||
- [x] `release/v2` has 562 commits not in `dev`; `dev` has 54 commits not in `release/v2`.
|
||||
- [x] The merge base is `2513e8454f240caa315b68dd6738b79838eeeecc` from 2026-08-13.
|
||||
- [x] The `dev...release/v2` change spans 2,473 files, 243,111 insertions and 59,966 deletions.
|
||||
- [x] A clean `git merge-tree --write-tree origin/dev origin/release/v2` rehearsal reports 42 unique conflict paths.
|
||||
- [x] The exact `release/v2` SHA has successful Fast gate, Container and E2E, CodeQL, Workshop validation and
|
||||
amd64/arm64 preview publication checks.
|
||||
- [x] The latest `dev` deployment workflow at `da32acb4f0ba9d8fa8e9667f56a54f85ca497865` is successful. An earlier
|
||||
arm64 offline-install failure was superseded by this green run.
|
||||
- [x] The Homarr preview manifest exists for amd64 and arm64:
|
||||
`ghcr.io/homarr-labs/homarr-test:v2@sha256:9055880e1d04ee78f2ff171ad8ff5ccd0b225e67e0a7635f4158669c40a8d7a0`.
|
||||
- [x] The Workshop preview manifest exists for amd64 and arm64:
|
||||
`ghcr.io/homarr-labs/workshop:v2@sha256:1578c7e68955395a533ea9a3afad1168331cb783bb98b0255c3ded5c0cd927f5`.
|
||||
- [x] PR [#6760](https://github.com/homarr-labs/homarr/pull/6760) merged the streamlined v2 documentation and
|
||||
passed its hosted checks.
|
||||
- [x] GitHub currently reports zero open CodeQL alerts and zero open secret-scanning alerts.
|
||||
- [x] All 65 open pull requests were inventoried: 36 target `dev`, 21 target `release/v2`, seven are internal stack
|
||||
layers and one targets `main`. Every one is classified below as review/merge, port, defer, superseded or cleanup.
|
||||
- [x] Audit-created readiness PRs #6770 through #6788 are non-draft, have clean merge state and have no failing or
|
||||
pending hosted checks. None has a human approval yet, and this evidence must be repeated after each rebase/merge
|
||||
wave.
|
||||
- [x] Repository Actions secret names include `DISCORD_WEBHOOK` and `DISCORD_WEBHOOK_AUTOMATIC_RELEASE`; values were
|
||||
not read. Their last name-level updates were 2024-02-03 and 2023-12-20, so delivery must still be tested.
|
||||
- [x] The `github-pages` environment has a deployment branch policy. The existing `prod` environment has no
|
||||
protection rules or reviewers and is not referenced by the production release workflow.
|
||||
- [x] The public v2 preview is reachable, redirects to the login page, accepts the advertised `demo` account and
|
||||
displays `Version 2.0.0` on `/manage/about`.
|
||||
- [x] A read-only Chromium smoke of the public preview loaded the populated dashboard without application console
|
||||
errors, completed an authenticated reload to network-idle in 3.2 seconds, opened the Date and time advanced view
|
||||
through its keyboard control, rendered three world clocks, and rendered populated Media Releases data. This does
|
||||
not replace final-candidate or real-provider testing.
|
||||
- [ ] GitHub Dependabot currently reports 168 open repository-wide alerts: 5 critical, 64 high, 82 medium and 17 low.
|
||||
These are based on the repository's default-branch dependency view and must be reconciled with the candidate-specific
|
||||
`pnpm audit` results.
|
||||
- [ ] No `v2.0.0` tag or production GitHub release exists yet. The latest production release is `v1.76.2`.
|
||||
- [ ] The `v2.0.0` milestone is still open but contains zero open issues and only one closed issue. It is not an
|
||||
adequate source of release truth.
|
||||
|
||||
### Merge batch update
|
||||
|
||||
- [x] `origin/release/v2` is `f1c898efe2da2fd55b26e2a674d7f67420acefee` after the release-readiness merge batch.
|
||||
- [x] PR #6770 and PRs #6772 through #6789 are merged into `release/v2`; every merge commit was verified as an
|
||||
ancestor of the remote branch.
|
||||
- [x] PR #6771 was closed by the release owner and was not merged.
|
||||
- [x] PR #6780 was rebased after the batch. Its environment-documentation conflict preserves both the public
|
||||
`BASE_URL` entry and the `NO_EXTERNAL_CONNECTION` location-search behavior.
|
||||
- [x] PR #6789 is limited to the Homarr 2.0 release article and its 20 media files.
|
||||
- [x] The v1-to-v2 guide tells users to export a backup from **Management → Tools → Backup** and keep the downloaded
|
||||
file somewhere safe before starting v2.
|
||||
- [ ] No combined final-candidate CI or test result is recorded for `f1c898efe`; per-PR checks were intentionally not
|
||||
followed during the merge batch. Run the final validation once the candidate is frozen.
|
||||
- [ ] PR #6765 is the only remaining open PR targeting `release/v2`. It is an external new integration/widget and was
|
||||
intentionally excluded from this maintainer release-cleanup batch.
|
||||
|
||||
### Readiness fixes opened from this audit
|
||||
|
||||
These statuses record whether each fix reached `release/v2`; they are not final release sign-offs. Carry the merged
|
||||
changes through the reviewed `release/v2 -> dev` integration and repeat the final-candidate checks.
|
||||
|
||||
- [x] [#6770](https://github.com/homarr-labs/homarr/pull/6770) — restore weekly release no-op behavior and scheduled
|
||||
Discord notifications, repair GitHub App token inputs, extend the merge timeout, and remove the obsolete release
|
||||
dispatch to the archived documentation repository.
|
||||
- [x] **CLOSED, NOT MERGED** [#6771](https://github.com/homarr-labs/homarr/pull/6771) — proposed making mock
|
||||
integrations opt-in and enforcing the unsafe flag in server-side creation, onboarding and direct-page paths.
|
||||
- [x] [#6772](https://github.com/homarr-labs/homarr/pull/6772) — generate valid integration documentation links and
|
||||
remove committed/generated `null` URLs.
|
||||
- [x] [#6773](https://github.com/homarr-labs/homarr/pull/6773) — point contributor guidance at the monorepo docs and
|
||||
current v2 branch flow.
|
||||
- [x] [#6774](https://github.com/homarr-labs/homarr/pull/6774) — add the canonical v1-to-v2 upgrade guide with concise
|
||||
Backup-tool guidance.
|
||||
- [x] [#6775](https://github.com/homarr-labs/homarr/pull/6775) — patch the critical Auth.js fail-open and email
|
||||
normalization advisories; 131 focused auth/proxy tests and affected typechecks pass.
|
||||
- [x] [#6776](https://github.com/homarr-labs/homarr/pull/6776) — patch the critical `protobufjs` path while staying on
|
||||
compatible 7.x; 24 Docker tests and affected typechecks pass.
|
||||
- [x] [#6777](https://github.com/homarr-labs/homarr/pull/6777) — replace the SQLite database placeholder with a
|
||||
safe ignored local path, remove copy-pastable weak secrets and delete the obsolete source-install
|
||||
`CRON_JOB_API_KEY` instruction. It also makes SSO key/credential replacement explicit and removes obsolete
|
||||
legacy URL entries; #6779 adds the current public `BASE_URL` contract. The production docs build and hosted Fast
|
||||
gate, amd64/arm64 preview builds, container/E2E tests and multi-platform preview publication all pass.
|
||||
- [x] [#6778](https://github.com/homarr-labs/homarr/pull/6778) — port the focused database-restore re-login and error
|
||||
reporting fix from #6624 without unrelated branch drift.
|
||||
- [x] [#6779](https://github.com/homarr-labs/homarr/pull/6779) — make MCP OAuth discovery, resource validation,
|
||||
authentication challenges and login redirects honor the public origin and supported MCP route aliases. Sixteen
|
||||
route tests, Next.js typecheck/build, docs build and production-server route smokes pass.
|
||||
- [x] [#6780](https://github.com/homarr-labs/homarr/pull/6780) — enforce `NO_EXTERNAL_CONNECTION` before weather
|
||||
location search makes an outbound request and show the disabled state. Fifteen focused tests and affected
|
||||
typechecks pass.
|
||||
- [x] [#6781](https://github.com/homarr-labs/homarr/pull/6781) — use Unraid's byte-based memory metrics and clamp
|
||||
inconsistent values instead of using layout metadata.
|
||||
- [x] [#6782](https://github.com/homarr-labs/homarr/pull/6782) — report Docker container CPU as a 0–100 percent share
|
||||
of the whole machine while retaining one-shot/Podman fallback behavior. Twenty focused tests pass.
|
||||
- [x] [#6783](https://github.com/homarr-labs/homarr/pull/6783) — sync the committed Helm page to live chart 8.28.2 /
|
||||
app v1.76.2. Regenerate it again from the v2 chart after that chart is published.
|
||||
- [x] [#6784](https://github.com/homarr-labs/homarr/pull/6784) — give the Downloads name column a stable default width
|
||||
without changing user-resizable persisted state.
|
||||
- [x] [#6785](https://github.com/homarr-labs/homarr/pull/6785) — support nested OIDC group/name claim paths while
|
||||
preserving v2's provider and verified-email linking safeguards. Twenty-three focused Auth tests pass.
|
||||
- [x] [#6786](https://github.com/homarr-labs/homarr/pull/6786) — preserve reverse-proxy subpaths in Nextcloud CalDAV
|
||||
discovery. Five focused Nextcloud tests pass.
|
||||
- [x] [#6787](https://github.com/homarr-labs/homarr/pull/6787) — use valid UniFi HTTPS default ports, preserve explicit
|
||||
ports and avoid hiding authentication failures. Six focused tests pass.
|
||||
- [x] [#6788](https://github.com/homarr-labs/homarr/pull/6788) — patch every published, fixable high-severity
|
||||
production dependency path found by the audit with exact catalog versions and range-scoped overrides. All
|
||||
workspace typechecks, the production docs build and 18 focused backup/ZIP tests pass. Its hosted Fast gate,
|
||||
amd64/arm64 preview builds, container/E2E tests and multi-platform preview publication all pass.
|
||||
- [x] [#6789](https://github.com/homarr-labs/homarr/pull/6789) — add the draft Homarr 2.0 release article and its 20
|
||||
referenced media files.
|
||||
- [x] A temporary combined audit of `origin/release/v2` plus #6775, #6776 and #6788 reports 0 critical, 2 high, 20
|
||||
moderate and 9 low production advisories. Both remaining high findings are Docusaurus build-time paths to
|
||||
`image-size@2.0.2`; the registry still reports 2.0.2 as latest while both advisories require `>=2.0.3`.
|
||||
- [x] That exact temporary combined graph also passes all 38 Turbo typecheck tasks and the Docusaurus production build.
|
||||
- [x] The five repository-wide critical Dependabot alerts were reconciled: three runtime Auth.js alerts are addressed
|
||||
by #6775, `protobufjs` is addressed by #6776, and the remaining `handlebars` alert is development-scoped and is not
|
||||
present in the candidate's production audit.
|
||||
|
||||
### Recommended review and merge order
|
||||
|
||||
- [ ] Merge #6769 early so the team works from this checklist; continue updating its evidence in the release tracking
|
||||
issue if the file itself is frozen.
|
||||
- [x] Merge the release-control and documentation fixes: #6770, #6772, #6773, #6774 and #6777. #6771 was closed by
|
||||
the release owner without merging.
|
||||
- [x] Merge the lockfile security chain in this order: #6775, rebase/re-audit #6776, then rebase/re-audit #6788. Do not
|
||||
resolve their shared lockfile conflicts by choosing one side wholesale.
|
||||
- [x] Merge the backup, public-origin, privacy, authentication and integration correctness fixes: #6778, #6779,
|
||||
#6780, #6785, #6786 and #6787.
|
||||
- [x] Merge the isolated display/metric fixes: #6781, #6782 and #6784.
|
||||
- [x] Merge #6783 with the current chart metadata.
|
||||
- [ ] Regenerate the Helm documentation after the v2 chart is published.
|
||||
- [ ] Decide #6765 explicitly before freeze. It is not ready to merge on the current evidence.
|
||||
- [x] Merge #6789 with the draft Homarr 2.0 article and its 20 media files.
|
||||
- [ ] Run combined checks on the frozen `release/v2` candidate. Per-PR CI was intentionally not followed during this
|
||||
merge batch and is not final-candidate evidence.
|
||||
|
||||
### Current merge conflicts
|
||||
|
||||
- [ ] `.agents/skills/codebase-context/SKILL.md`
|
||||
- [ ] `.agents/skills/datatable-migration/SKILL.md`
|
||||
- [ ] `.agents/skills/documentation-sync/SKILL.md`
|
||||
- [ ] `.agents/skills/mcp-integration/SKILL.md`
|
||||
- [ ] `.mcp.json`
|
||||
- [ ] `AGENTS.md`
|
||||
- [ ] `apps/docs/docs/getting-started/installation/helm.md`
|
||||
- [ ] `apps/docs/docs/management/certificates/index.mdx`
|
||||
- [ ] `apps/docs/docs/widgets/app/index.mdx`
|
||||
- [ ] `apps/docs/docs/widgets/bookmarks/index.mdx`
|
||||
- [ ] `apps/docs/docs/widgets/smart-home-entity-state/index.mdx`
|
||||
- [ ] `apps/docs/docs/widgets/smart-home-execute-automation/index.mdx`
|
||||
- [ ] `apps/nextjs/src/app/api/mcp/[transport]/route.ts`
|
||||
- [ ] `apps/nextjs/src/components/board/items/widget-context-menu.tsx`
|
||||
- [ ] `apps/nextjs/src/components/board/sections/gridstack/use-gridstack.ts`
|
||||
- [ ] `e2e/onboarding.spec.ts`
|
||||
- [ ] `package.json`
|
||||
- [ ] `packages/api/src/router/widgets/smart-home.ts`
|
||||
- [ ] `packages/integrations/src/truenas/test/truenas-integration.spec.ts`
|
||||
- [ ] `packages/translation/src/lang/ca.json`
|
||||
- [ ] `packages/translation/src/lang/cs.json`
|
||||
- [ ] `packages/translation/src/lang/de-CH.json`
|
||||
- [ ] `packages/translation/src/lang/el.json`
|
||||
- [ ] `packages/translation/src/lang/en-gb.json`
|
||||
- [ ] `packages/translation/src/lang/es.json`
|
||||
- [ ] `packages/translation/src/lang/et.json`
|
||||
- [ ] `packages/translation/src/lang/fr.json`
|
||||
- [ ] `packages/translation/src/lang/hr.json`
|
||||
- [ ] `packages/translation/src/lang/hu.json`
|
||||
- [ ] `packages/translation/src/lang/lt.json`
|
||||
- [ ] `packages/translation/src/lang/lv.json`
|
||||
- [ ] `packages/translation/src/lang/no.json`
|
||||
- [ ] `packages/translation/src/lang/pt-br.json`
|
||||
- [ ] `packages/translation/src/lang/pt.json`
|
||||
- [ ] `packages/translation/src/lang/ro.json`
|
||||
- [ ] `packages/translation/src/lang/ru.json`
|
||||
- [ ] `packages/translation/src/lang/sl.json`
|
||||
- [ ] `packages/translation/src/lang/sv.json`
|
||||
- [ ] `packages/translation/src/lang/uk.json`
|
||||
- [ ] `packages/translation/src/lang/vi.json`
|
||||
- [ ] `packages/widgets/src/health-monitoring/component.tsx`
|
||||
- [ ] `packages/widgets/src/system-disks/component.tsx`
|
||||
|
||||
## Current hard blockers
|
||||
|
||||
- [ ] **BLOCKER — integrate histories:** reconcile all 54 `dev`-only commits and resolve the 42 current merge
|
||||
conflicts without dropping either branch's behavior.
|
||||
- [ ] **BLOCKER — production dependency audit:** the baseline `mise exec -- pnpm audit --prod --audit-level high`
|
||||
reported 141 findings: 4 critical, 65 high, 62 moderate and 10 low. The isolated combined graph with #6775,
|
||||
#6776 and #6788 has 0 critical, 2 high, 20 moderate and 9 low. Those fixes are merged; repeat the audit on the
|
||||
exact frozen candidate and explicitly accept or wait for a published `image-size` fix.
|
||||
- [ ] **BLOCKER — direct authentication advisories:** #6775 is merged. Revalidate every authentication provider on the
|
||||
combined candidate and confirm the critical `next-auth` and `@auth/core` findings remain absent.
|
||||
- [ ] **BLOCKER — weekly promotion automation:** #6770 is merged. Prove its success, failure and no-release paths in
|
||||
controlled workflow runs.
|
||||
- [ ] **BLOCKER — scheduled notifications:** #6770 is merged. Prove scheduled start, success, major and failure notices
|
||||
in a non-public Discord channel.
|
||||
- [ ] **BLOCKER — MCP public origin:** #6779 is merged. Repeat discovery/login/401 challenges through the actual
|
||||
production reverse proxy and subpath before publishing MCP as GA-ready.
|
||||
- [ ] **BLOCKER — documentation release:** #6770 removed the false handoff to the archived
|
||||
`homarr-labs/documentation` repository. Confirm the authoritative monorepo GitHub Pages workflow deploys
|
||||
`apps/docs` when the v2 docs reach `dev`, then verify the public site and Algolia recrawl.
|
||||
- [ ] **BLOCKER — branch rules:** the strong `v2 release` ruleset targets the legacy `refs/heads/v2`, not
|
||||
`refs/heads/release/v2`. The active release branch does not receive those required checks.
|
||||
- [ ] **BLOCKER — production deployment guard:** the release workflow publishes after a `main` push without a
|
||||
protected production environment, while `main` currently requires no status checks. Decide and test the exact
|
||||
human approval/check boundary before the release window.
|
||||
- [ ] **BLOCKER — final upgrade rehearsal:** perform backup, migration, restore and rollback rehearsals from real
|
||||
`v1.76.2` installations for SQLite, MySQL and PostgreSQL.
|
||||
- [ ] **BLOCKER — upgrade guide:** #6774 is merged with the concise Backup-tool instruction. Verify the guide against
|
||||
real upgrade and restore rehearsals and the final image/tag.
|
||||
- [ ] **BLOCKER — beta feedback:** reproduce or close every unresolved report in the public v2 beta issue.
|
||||
- [ ] **BLOCKER — release scope:** explicitly include or defer the open llama.cpp PR and every release-sensitive fix
|
||||
listed below before feature freeze.
|
||||
- [ ] **BLOCKER — production defaults:** #6771 was closed without merging. Confirm that decision against the combined
|
||||
candidate's mock-integration API/UI behavior or record explicit risk acceptance.
|
||||
- [ ] **BLOCKER — final immutable candidate:** nominate one SHA, freeze it, and repeat all mandatory checks on that
|
||||
exact SHA after it is in `dev`.
|
||||
|
||||
## 1. Ownership and release control
|
||||
|
||||
- [ ] Name the release owner: `________________`.
|
||||
- [ ] Name the database/backup owner: `________________`.
|
||||
- [ ] Name the infrastructure/GHCR owner: `________________`.
|
||||
- [ ] Name the documentation owner: `________________`.
|
||||
- [ ] Name the Workshop owner: `________________`.
|
||||
- [ ] Name the Discord/support owner: `________________`.
|
||||
- [ ] Agree on the feature-freeze time: `________________`.
|
||||
- [ ] Agree on the production merge window: `________________`.
|
||||
- [ ] Agree on rollback decision authority: `________________`.
|
||||
- [ ] Create one release tracking issue and copy/link this checklist there if GitHub assignment is required.
|
||||
- [ ] Assign an owner and deadline to every accepted blocker.
|
||||
- [ ] Record explicit written acceptance for any unresolved non-blocking risk.
|
||||
- [ ] Confirm at least two humans will attend the final go/no-go and release window.
|
||||
|
||||
## 2. Integrate `release/v2` into `dev`
|
||||
|
||||
- [ ] Freeze new features on `release/v2`.
|
||||
- [ ] Refresh `origin/main`, `origin/dev`, `origin/release/v2`, tags, PRs and rulesets.
|
||||
- [ ] Create a temporary integration branch from the current `origin/dev`.
|
||||
- [ ] Merge `origin/release/v2` into that integration branch.
|
||||
- [ ] Resolve every conflict semantically; do not choose an entire side for translations, migrations, docs or APIs
|
||||
without reviewing both changes.
|
||||
- [ ] Re-run the merge rehearsal and confirm zero unresolved entries.
|
||||
- [ ] Review every `dev`-only commit and mark it as preserved, superseded or intentionally rejected.
|
||||
- [ ] Specifically preserve or reconcile current `dev` changes for:
|
||||
- [ ] startup/internal service addresses
|
||||
- [ ] MCP void results
|
||||
- [ ] Home Assistant actions and smart-home refresh behavior
|
||||
- [ ] TrueNAS dataset/pool calculations
|
||||
- [ ] OMV disk-temperature matching
|
||||
- [ ] Unraid CPU/link/board fixes
|
||||
- [ ] custom PUID/PGID startup behavior
|
||||
- [ ] Helm documentation
|
||||
- [ ] contributor and bug-report automation
|
||||
- [ ] all Crowdin translation updates
|
||||
- [ ] Confirm root `package.json` remains version `2.0.0`.
|
||||
- [ ] Confirm the final promotion commit/PR contains a breaking Conventional Commit signal such as
|
||||
`feat!: release Homarr v2`.
|
||||
- [ ] Regenerate the lockfile only after dependency and conflict decisions are final.
|
||||
- [ ] Open the reviewed integration branch as the actual promotion PR into `dev`.
|
||||
- [ ] Require human review and resolve every thread.
|
||||
- [ ] Do not use PR #6545 as the production promotion PR; it targets an internal stacked branch.
|
||||
|
||||
## 3. Pull-request triage
|
||||
|
||||
Every open PR must be marked `include`, `port only`, `defer`, `superseded`, or `close`. New features should default to
|
||||
defer once the release is frozen.
|
||||
|
||||
### Release-sensitive decisions
|
||||
|
||||
- [ ] [#6765 llama.cpp integration and widget](https://github.com/homarr-labs/homarr/pull/6765) — currently targets
|
||||
`release/v2`, is unstable, has no approval, lacks full CI on its newest head, and has requested responsive/advanced
|
||||
mode work. Finish it completely or defer it before integration.
|
||||
- [x] **PORT ONLY** [#6624 backup restore re-login](https://github.com/homarr-labs/homarr/pull/6624) — focused v2
|
||||
port opened as #6778; do not merge unrelated branch drift.
|
||||
- [x] **PORT ONLY** [#6631 MCP OAuth base URL](https://github.com/homarr-labs/homarr/pull/6631) — expanded and
|
||||
production-smoked current-v2 port opened as #6779.
|
||||
- [x] **SUPERSEDED** [#6662 board access-control form](https://github.com/homarr-labs/homarr/pull/6662) — current
|
||||
`release/v2` already renders the access/danger forms outside the unified outer form; no duplicate port required.
|
||||
- [x] **PORT ONLY** [#6674 weather and `NO_EXTERNAL_CONNECTION`](https://github.com/homarr-labs/homarr/pull/6674) —
|
||||
focused current-v2 privacy/offline port opened as #6780.
|
||||
- [x] **PORT ONLY** [#6749 Unraid memory utilization](https://github.com/homarr-labs/homarr/pull/6749) — focused
|
||||
current-v2 metric fix opened as #6781.
|
||||
- [x] **PORT ONLY** [#6250 container CPU utilization](https://github.com/homarr-labs/homarr/pull/6250) — focused
|
||||
current-v2 normalization fix opened as #6782.
|
||||
- [x] **PORT ONLY** [#6733 Helm documentation](https://github.com/homarr-labs/homarr/pull/6733) — current chart
|
||||
metadata port opened as #6783; regenerate again after publishing the v2 chart.
|
||||
- [x] **DEFER WHOLESALE** [#6601 broad dependency update](https://github.com/homarr-labs/homarr/pull/6601) — its
|
||||
6,000-line lock/dependency churn is not a safe release patch. Use #6775, #6776 and #6788 for the focused
|
||||
candidate-specific security work.
|
||||
|
||||
### Feature/UI candidates to include or defer explicitly
|
||||
|
||||
- [x] **DEFER** #6657 OMV volume selection — feature work, not a GA blocker.
|
||||
- [x] **DEFER** #6645 Beszel GPU metrics — feature work, not a GA blocker.
|
||||
- [x] **PORT ONLY** #6621 Downloads column width — minimal current-v2 fix opened as #6784; supersedes #6122.
|
||||
- [x] **DEFER** #6603 isolated pnpm linker/phantom dependencies — broad package-manager/workspace refactor.
|
||||
- [x] **DEFER** #6572 Hermes Agent integration — large new integration and widget.
|
||||
- [x] **DEFER** #6562 favicon detection — new network-facing app-form behavior.
|
||||
- [x] **DEFER** #6561 Komodo integration — large new integration.
|
||||
- [x] **DEFER** #6546 REST dashboard automation — large API expansion; release separately after threat-model review.
|
||||
- [x] **DEFER** #6537 dashboard memory work — very large conflicting performance branch; benchmark separately.
|
||||
- [x] **DEFER** #6518 Sportarr integration — new integration.
|
||||
- [x] **DEFER** #6517 UGOS integration — conflicting new integration.
|
||||
- [x] **DEFER** #6515 SABnzbd archived-history options — changes requested remain.
|
||||
- [x] **DEFER** #6458 API add-item section targeting — changes requested remain.
|
||||
- [x] **DEFER** #6393 board keyboard shortcuts — conflicting feature work.
|
||||
- [x] **PORT ONLY** #6295 Nextcloud subpath fix — current-v2 port opened as #6786.
|
||||
- [x] **PORT ONLY** #6294 nested OIDC claims — current-v2 port opened as #6785 while preserving newer auth guards.
|
||||
- [x] **PORT ONLY** #6210 UniFi default ports — cleaned current-v2 port opened as #6787.
|
||||
- [x] **SUPERSEDED** #6148 path-only app URLs — current v2 already accepts safe same-origin paths and blocks unsafe
|
||||
schemes through `getSafeAppHref`; #5595 is also superseded.
|
||||
|
||||
### Remaining open `dev` candidates
|
||||
|
||||
- [x] **DEFER** #6214 disabled users, #6140 Dawarich, #6144 FileFlows, #6145 Pushover, #4957 Incus and #4549
|
||||
automatic layout — drafts, conflicting branches or new-feature scope.
|
||||
- [x] **CLOSE/SUPERSEDED** #6132 dependency group — stale/conflicting dependency churn; use candidate-specific
|
||||
advisory fixes.
|
||||
- [ ] Confirm the release owner accepts every recommended `DEFER` classification above before feature freeze.
|
||||
|
||||
### Stack and stale-PR cleanup
|
||||
|
||||
- [ ] Close or reframe #6545 after the real promotion PR exists.
|
||||
- [ ] Close internal stack PRs #6569, #6555, #6503, #6502, #6482, #6450 and #6356 after confirming their commits
|
||||
are present in `release/v2`.
|
||||
- [x] **CLOSE** classification recorded for #6549: its head and base are both `dev`, and its history includes
|
||||
acknowledged unrelated media changes despite approval.
|
||||
- [ ] Close #6549 after preserving any unique issue/history references.
|
||||
- [x] **CLOSE/SUPERSEDED** classifications recorded for #6122, #6148, #5595, #6621, #6624, #6631, #6674, #6749,
|
||||
#6250, #6294, #6295, #6210 and #6733 after their current-v2 replacement or source-equivalent behavior is merged.
|
||||
- [ ] Close those source/duplicate PRs only after the replacement PRs land and their history is linked.
|
||||
- [ ] Move all accepted deferred work to a `v2.0.x` or `v2.1` milestone.
|
||||
- [ ] Confirm no open PR still targets `release/v2` when the candidate is frozen.
|
||||
|
||||
### Documentation and announcement branches
|
||||
|
||||
- [x] PR #6760 is merged into `release/v2`.
|
||||
- [ ] Do not merge `origin/feat/homarr-v2-release-blog` wholesale. It remains two commits behind and nine ahead, but
|
||||
changes 199 files, combines the article with a broad documentation rewrite, deletes many current screenshots and
|
||||
includes `apps/docs/.release-research/` scratch material.
|
||||
- [ ] Split a focused release-material branch containing only the reviewed Homarr 2.0 blog, required media and
|
||||
GitHub/Reddit/Discord announcement variants; rebase that branch after the product/docs freeze.
|
||||
- [ ] Remove private release-research files from the publishable diff.
|
||||
- [ ] Replace announcement links to internal stack PR #6545 with the real promotion/release URL.
|
||||
- [ ] Replace GA announcement calls to the preview/beta thread with the production release, upgrade guide and support
|
||||
destinations; keep a beta link only if it serves a deliberate archival purpose.
|
||||
- [ ] Update the blog path/date if the final publication date differs from `2026/09/03`.
|
||||
|
||||
## 4. Security and privacy gate
|
||||
|
||||
- [ ] Re-run `mise exec -- pnpm audit --prod --audit-level high` on the final candidate.
|
||||
- [ ] Reduce all critical production-reachable findings to zero.
|
||||
- [ ] Merge #6775's patched `@auth/core` release and validate every authentication provider on the final candidate.
|
||||
- [ ] Merge #6775's patched `next-auth` release and validate failure-open, email normalization and session behavior on
|
||||
the final candidate.
|
||||
- [ ] Merge #6776's patched `protobufjs` 7.x resolution and rerun the audit on the final candidate.
|
||||
- [ ] Merge #6788 after #6775 and #6776, resolve/review the resulting lockfile once, and repeat its typecheck, docs,
|
||||
container and production-audit evidence on the rebased head.
|
||||
- [ ] Resolve the repository-wide development-scoped `handlebars` alert separately or record why it does not block
|
||||
production; it is not present in the candidate's production dependency audit.
|
||||
- [x] #6788 patches the audited high findings for `undici`, `adm-zip`, `fast-xml-parser`, `axios`, `postcss`,
|
||||
`serialize-javascript`, `fast-uri`, `js-yaml`, `brace-expansion`, `find-my-way`, `immutable`, `svgo`, `shell-quote`,
|
||||
`@xmldom/xmldom` and their affected paths; #6776 patches `protobufjs`.
|
||||
- [ ] Record a time-bounded risk decision for the two `image-size` highs. They are limited to Docusaurus MDX image
|
||||
processing during the docs build, but no patched package is currently published. Upgrade immediately when
|
||||
`image-size>=2.0.3` becomes available, or hold GA if the security owner does not accept that build-time exposure.
|
||||
- [ ] For every accepted advisory, record package path, runtime reachability, mitigating controls, owner and target
|
||||
patch release.
|
||||
- [ ] Confirm CodeQL has no open alert on the final SHA.
|
||||
- [ ] Confirm secret scanning has no open alert on the final SHA.
|
||||
- [ ] Review authentication, API keys, session invalidation, CSRF and authorization boundaries.
|
||||
- [ ] Test OIDC, credentials authentication and LLDAP using non-admin and admin users.
|
||||
- [ ] Test board, integration, app, user, group, API, MCP and settings permissions.
|
||||
- [ ] Verify public boards never expose private integrations, secrets, Custom Widget credentials or assistant context.
|
||||
- [ ] Verify logs, analytics and error messages redact tokens, passwords, headers and URLs containing credentials.
|
||||
- [ ] Verify Custom Widget URL/SSRF, secret, preview-action and sandbox boundaries.
|
||||
- [ ] Verify MCP destructive tools are permission-checked and clearly described.
|
||||
- [ ] Review GitHub Actions permissions; repository workflows currently default to write and can approve PRs.
|
||||
- [ ] Decide whether release workflows must pin third-party actions to immutable SHAs. SHA pinning is not currently
|
||||
required.
|
||||
|
||||
## 5. Database migration, backup and rollback
|
||||
|
||||
v2 adds parallel migrations for Custom Widget v2 tables, layout gutters, layout roles, assistant tables, and header
|
||||
preferences/branding to SQLite, MySQL and PostgreSQL, plus the custom section/gutter migration.
|
||||
|
||||
### Automated migration validation
|
||||
|
||||
- [ ] SQLite migration suite passes on the final candidate.
|
||||
- [ ] MySQL migration suite passes on the final candidate.
|
||||
- [ ] PostgreSQL migration suite passes on the final candidate.
|
||||
- [ ] Migration journal integrity suite passes.
|
||||
- [ ] Schema parity checks pass.
|
||||
- [ ] Custom Widget v1 data/board-reference preservation tests pass for all three drivers.
|
||||
- [ ] Backup import/export, concurrent restore and temporary-directory cleanup tests pass.
|
||||
- [ ] Same-key and changed-key secret re-encryption tests pass.
|
||||
|
||||
### Real upgrade rehearsal — repeat for every driver
|
||||
|
||||
- [ ] Use a representative `v1.76.2` installation with users, groups, boards, apps, integrations, secrets, media,
|
||||
tasks and Custom Widgets.
|
||||
- [ ] Record source version, database driver, architecture, image digest and backup checksum.
|
||||
- [ ] Back up the database, `/appdata`, certificates and exact `SECRET_ENCRYPTION_KEY`.
|
||||
- [ ] Upgrade using the exact final-candidate image digest.
|
||||
- [ ] Confirm migrations run exactly once and startup becomes healthy.
|
||||
- [ ] Restart again and confirm migrations do not repeat or corrupt state.
|
||||
- [ ] Verify users, groups, sessions, API keys and permission scopes.
|
||||
- [ ] Verify boards, sections, containers, rails, layouts, gutters and breakpoints.
|
||||
- [ ] Verify apps, integrations, encrypted secrets and search engines.
|
||||
- [ ] Verify Custom Widget v1 archives and v2 definitions/secrets.
|
||||
- [ ] Verify assistant configuration/history and branding/header preferences.
|
||||
- [ ] Export a v2 backup and restore it into a clean v2 deployment.
|
||||
- [ ] Confirm restore explains session invalidation and sends the user cleanly to sign-in.
|
||||
- [ ] Test a backup made with a different encryption key.
|
||||
- [ ] Test a corrupt, incomplete, oversized and wrong-driver backup.
|
||||
- [ ] Restore the original v1 backup as the rollback rehearsal.
|
||||
- [ ] State clearly whether v1 can open a v2-migrated database. If unsupported, prohibit rollback with the migrated
|
||||
database and require restoration of the pre-upgrade backup.
|
||||
|
||||
## 6. Product acceptance matrix
|
||||
|
||||
### Installation and runtime
|
||||
|
||||
- [ ] Docker Compose fresh install.
|
||||
- [ ] Docker Compose upgrade from `v1.76.2`.
|
||||
- [ ] amd64 image.
|
||||
- [ ] arm64 image, including Raspberry Pi-class hardware.
|
||||
- [ ] SQLite, MySQL and PostgreSQL.
|
||||
- [ ] Internal Redis and external Redis.
|
||||
- [ ] Reverse proxy with HTTPS and WebSocket forwarding.
|
||||
- [ ] IPv4-only, IPv6-only where supported, and dual-stack behavior.
|
||||
- [ ] Custom PUID/PGID with bind mounts and named volumes.
|
||||
- [ ] Docker and Podman sockets, including multiple socket configuration.
|
||||
- [ ] Kubernetes and current Helm chart.
|
||||
- [ ] Unraid, TrueNAS, Synology, QNAP, Portainer and Proxmox documented paths.
|
||||
- [ ] Source installation with Node 24.18.0 and pnpm 11.15.1.
|
||||
- [ ] `_FILE` secret variants and trusted certificates.
|
||||
- [ ] Restart, health-check and graceful-shutdown behavior.
|
||||
- [ ] Offline/`NO_EXTERNAL_CONNECTION` behavior.
|
||||
- [ ] Low-memory startup and a large real dashboard.
|
||||
|
||||
### Authentication, users and onboarding
|
||||
|
||||
- [ ] Fresh onboarding from first request to usable admin dashboard.
|
||||
- [ ] Upgrade bypasses onboarding correctly.
|
||||
- [ ] Local sign-in, sign-out, expiry, invalid credentials and password recovery.
|
||||
- [ ] OIDC and LLDAP sign-in, account linking and logout.
|
||||
- [ ] Admin and non-admin navigation.
|
||||
- [ ] Create, edit, disable/delete and restore users where supported.
|
||||
- [ ] Create groups, assign members and verify permission inheritance.
|
||||
- [ ] Public/private board access and home-board selection.
|
||||
- [ ] Authentication branding/background does not disclose private app or integration data.
|
||||
|
||||
### Boards and layouts
|
||||
|
||||
- [ ] Create, rename, duplicate, import, export and delete a board.
|
||||
- [ ] Create/edit/delete sections, containers and rails.
|
||||
- [ ] Drag, resize, multi-move and move into/out of containers.
|
||||
- [ ] Responsive Base, Custom and Mobile layout selection and repair.
|
||||
- [ ] Sidebars and collapsible/scrollable containers.
|
||||
- [ ] Empty-board and missing-board states.
|
||||
- [ ] Edit/view mode transitions, context menus and keyboard interactions.
|
||||
- [ ] Mobile phone, tablet, 1080p dense grid and large desktop viewport.
|
||||
- [ ] Light/dark theme, background, border radius and custom CSS.
|
||||
- [ ] Undo/redo/reset behavior where exposed.
|
||||
|
||||
### Apps, search and management
|
||||
|
||||
- [ ] App create/edit/delete, favicon/icon selection, ping and Docker association.
|
||||
- [ ] Integration create/edit/test/delete and app linking.
|
||||
- [ ] Search engines, DDG bangs and external search.
|
||||
- [ ] Spotlight modes, commands and permission filtering.
|
||||
- [ ] Media management and release search.
|
||||
- [ ] Logs, contextual widget timestamps and redaction.
|
||||
- [ ] Task list, manual trigger, cron status and Redis reconnect.
|
||||
- [ ] Certificates add/remove/use flow.
|
||||
- [ ] Backup download and restore flow.
|
||||
- [ ] Server settings, analytics consent, culture, branding and global custom CSS.
|
||||
|
||||
### Widgets and integrations
|
||||
|
||||
- [ ] Run documentation coverage validation for every registered widget/integration slug.
|
||||
- [ ] Smoke every one of the 59 current widget documentation categories against its actual widget definition.
|
||||
- [ ] Smoke each integration family with a real service or documented representative fixture.
|
||||
- [ ] Validate normal, loading, empty, partial-data, authentication-error, timeout and offline states.
|
||||
- [ ] Validate widget context menus, edit forms, optional integrations and advanced mode.
|
||||
- [ ] Validate cache/refetch behavior and WebSocket updates.
|
||||
- [ ] Validate chart labels, tables and text at dense/small sizes.
|
||||
- [ ] Validate integration actions such as Docker, DNS, download, smart-home and media requests.
|
||||
- [ ] Confirm unsupported upstream metrics are shown as unavailable rather than fabricated zeroes.
|
||||
|
||||
### Custom Widgets, Assistant, MCP and Workshop
|
||||
|
||||
- [ ] Custom Widget create, import, edit, validate, preview, save, install, update, uninstall and rollback.
|
||||
- [ ] Custom Widget queries/actions, redacted journal, secrets and invalidation behavior.
|
||||
- [ ] Workshop browse, search, detail, screenshot, comments, authentication, publishing and moderation.
|
||||
- [ ] Workshop outage does not break already-installed widgets.
|
||||
- [ ] Assistant configuration for Homarr, OpenRouter, Ollama and applicable compatible providers.
|
||||
- [ ] Assistant conversation, tools, custom CSS and Custom Widget authoring.
|
||||
- [ ] Assistant consent/privacy claims match actual telemetry and provider behavior.
|
||||
- [ ] MCP HTTP transport, authentication, OAuth discovery/login, API-key access and error responses.
|
||||
- [ ] Decide whether Custom Widgets and Workshop remain labelled experimental for GA and define their support policy.
|
||||
|
||||
### Browser, accessibility and performance
|
||||
|
||||
- [ ] Chromium final-candidate E2E passes.
|
||||
- [ ] Firefox smoke passes; current automated E2E is Chromium-only.
|
||||
- [ ] WebKit/Safari smoke passes if it is in the supported browser matrix.
|
||||
- [ ] Keyboard-only navigation and visible focus states.
|
||||
- [ ] Screen-reader labels for forms, dialogs, menus and live restore states.
|
||||
- [ ] Reduced-motion behavior and acceptable color contrast.
|
||||
- [ ] Compare v1.76.2 and v2 cold start, server memory, browser memory and dashboard refresh time.
|
||||
- [ ] Confirm no sustained request storm or duplicate subscriptions on large dashboards.
|
||||
- [ ] Confirm widgets do not take the beta-reported 72 seconds to recover after a full page refresh.
|
||||
|
||||
## 7. Public beta feedback closure
|
||||
|
||||
Track every report from [issue #6600](https://github.com/homarr-labs/homarr/issues/6600) with a reproducer and fix,
|
||||
or a linked issue and explicit defer decision.
|
||||
|
||||
- [ ] Dense Beszel/widget text scaling — current `release/v2` contains merged #6616; still retest the reported
|
||||
13/23/24-column layouts on the final candidate.
|
||||
- [ ] Incorrect v1.74 update indicator — the current public preview displays `Version 2.0.0`; still verify the final
|
||||
immutable image and update checker report the production tag without a false update.
|
||||
- [ ] Full-page widget refresh reported as roughly 5 seconds in v1 versus 72 seconds in v2 — the 2026-09-06 public
|
||||
demo smoke completed an authenticated network-idle reload in 3.2 seconds with no application console errors.
|
||||
Repeat with a large real-provider dashboard and profile server/browser memory before closing.
|
||||
- [x] Date/time widget missing world clocks — reproduced as fixed on the current public preview: keyboard activation
|
||||
opened advanced view with New York, Paris and Tokyo clocks. Retest the final candidate after freeze.
|
||||
- [ ] Media Releases widget reported non-functional — current public demo advanced view renders seven populated mock
|
||||
releases. Repeat with every supported real provider before closing the report.
|
||||
- [ ] Compact bookmarks reported as not compact — current `release/v2` contains merged #6747; visually retest all
|
||||
supported sizes and mobile layouts.
|
||||
- [x] No new beta-thread comments were present after 2026-08-29 when refreshed on 2026-09-06.
|
||||
- [ ] Review the beta issue again for new comments immediately before freeze.
|
||||
- [ ] Reply with fix/issue links so testers know each report's disposition.
|
||||
- [ ] Close or convert the beta thread only after all reports have a disposition.
|
||||
|
||||
## 8. Documentation and placeholder cleanup
|
||||
|
||||
### User documentation
|
||||
|
||||
- [ ] Review and merge #6774's canonical `Upgrade from v1 to v2` page.
|
||||
- [ ] Cover backup prerequisites, database migrations, changed environment variables and rollback limitations.
|
||||
- [ ] Cover Custom Widget v1-to-v2 migration and archived definitions.
|
||||
- [ ] Cover Workshop data/volume backup and restore.
|
||||
- [ ] Cover Docker, Helm/Kubernetes, Unraid, TrueNAS, Synology, QNAP, Portainer, Proxmox and source upgrades.
|
||||
- [ ] List removed/renamed behavior and known issues.
|
||||
- [ ] Verify all environment defaults, image names, ports, paths and commands against source.
|
||||
- [ ] Run `mise exec -- pnpm turbo build --filter=@homarr/docs` on the final docs commit.
|
||||
- [ ] Treat every broken link, missing image and invalid MDX page as a blocker.
|
||||
- [ ] Verify generated integration/widget coverage after the final registry is frozen.
|
||||
- [ ] Verify screenshots against the final UI on desktop and mobile.
|
||||
- [ ] Verify Algolia indexing/recrawl after deployment.
|
||||
- [ ] Decide whether merging v2 into `dev` may publish GA-oriented docs before the application release.
|
||||
|
||||
### Repository and placeholder cleanup
|
||||
|
||||
- [ ] Review and merge #6773's `.github/pull_request_template.md` update; it points documentation changes at the
|
||||
monorepo and describes the current v2 branch flow.
|
||||
- [ ] Decide whether to restore a root `README.md`. Only `docs/README.md` currently exists.
|
||||
- [ ] Review and merge #6772; it replaces the seven committed `href="null"` integration links and makes the generator
|
||||
use canonical integration documentation URLs.
|
||||
- [ ] Review and merge #6777; it replaces `.env.example`'s SQLite database placeholder with the runnable
|
||||
source-development path `./db.sqlite`, documents the separate `/appdata/db/db.sqlite` container default and keeps
|
||||
other database examples commented.
|
||||
- [ ] Review and merge #6771; it comments out `UNSAFE_ENABLE_MOCK_INTEGRATION` in `.env.example`.
|
||||
- [ ] Repeat #6771's disabled/enabled direct URL, API creation and onboarding smoke on the final candidate.
|
||||
- [ ] Review and merge #6777's removal of copy-pastable `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` values; confirm the
|
||||
final source-install guide requires two different random values.
|
||||
- [ ] Keep intentional UI input placeholders, test-domain `example.com` values, the Workshop password replacement
|
||||
example and media-year `TBD`; these are not unfinished product copy.
|
||||
- [ ] Run another focused scan for TODO, TBD, lorem ipsum, coming soon, `href="null"`, fake URLs, temporary files,
|
||||
screenshots from previews and beta-only wording.
|
||||
|
||||
### Release article and notes
|
||||
|
||||
- [ ] Rebase and review `feat/homarr-v2-release-blog` after all product decisions are final.
|
||||
- [ ] Ensure article claims about performance, privacy, features and compatibility have current evidence.
|
||||
- [ ] Curate release notes; autogenerated notes from 562 release-branch commits are not sufficient by themselves.
|
||||
- [ ] Run Semantic Release in dry-run mode from a faithful final-candidate branch and inspect the proposed version and
|
||||
changelog.
|
||||
- [ ] Ensure the draft GitHub release body stays below GitHub limits and links to the upgrade guide.
|
||||
|
||||
## 9. Workshop production readiness
|
||||
|
||||
- [ ] Decide the production Workshop domain, `WORKSHOP_API_URL`, `WORKSHOP_WEB_URL` and `WORKSHOP_PUBLIC_ORIGIN`.
|
||||
- [ ] Snapshot the PocketBase database, files and configuration.
|
||||
- [ ] Rehearse the documented v2 Workshop migration/restore procedure.
|
||||
- [ ] Verify GitHub OAuth callback URLs and credentials.
|
||||
- [ ] Verify allowed origins, email links, administrator access and moderation.
|
||||
- [ ] Test amd64 and arm64 Workshop images by immutable digest.
|
||||
- [ ] Promote the exact approved Workshop digest from `:v2` to its production tag.
|
||||
- [ ] Verify Workshop health and a Homarr install/update flow after production promotion.
|
||||
- [ ] Verify docs continue to build and render if Workshop is unavailable.
|
||||
- [ ] Define Workshop rollback separately from the Homarr application rollback.
|
||||
|
||||
## 10. CI/CD production readiness
|
||||
|
||||
### Fix before promotion
|
||||
|
||||
- [ ] Merge #6770, then prove the weekly workflow exits successfully with a clear `no releasable change` result when
|
||||
Semantic Versioning finds no bump.
|
||||
- [ ] Merge #6770, then prove scheduled runs notify by default and manual runs respect the notification checkbox.
|
||||
- [ ] Prove weekly success, failure and major-release/manual-merge paths in controlled runs.
|
||||
- [ ] Correct the `v2 release` ruleset target or remove the stale legacy branch/rule after preserving required checks.
|
||||
- [ ] Add required final checks to `main`; its current productive ruleset requires review but no status checks.
|
||||
- [ ] Require at least one human approval, resolved threads, stale-approval dismissal and no force push/deletion for the
|
||||
final promotion.
|
||||
- [ ] Review ruleset bypass actors and limit release bypasses to the necessary bots/owners.
|
||||
- [ ] Protect a real production deployment environment and bind the irreversible Semantic Release/tag/publish path to
|
||||
it, or record an explicit alternative control. The current unprotected, unused `prod` environment is not a gate.
|
||||
- [ ] Merge #6770's removal of the false archived-repository handoff and verify the monorepo `dev` docs deployment is
|
||||
authoritative.
|
||||
- [ ] Review and merge #6770's explicit production deployment failure/cancellation notification.
|
||||
- [ ] Review and merge #6770's mandatory post-release check that verifies `dev` contains the Semantic Release commit
|
||||
after synchronization; prove the verification fails loudly when synchronization is incomplete.
|
||||
- [ ] Decide whether the absent `beta` branch is intentional. Remove dead beta logic or create/test a real RC path.
|
||||
- [ ] Verify a manual dispatch redeploys the latest existing release and cannot create an unintended tag.
|
||||
|
||||
### Final candidate checks
|
||||
|
||||
- [ ] Formatting.
|
||||
- [ ] Lint.
|
||||
- [ ] Full typecheck.
|
||||
- [ ] Full production build.
|
||||
- [ ] Complete unit suite.
|
||||
- [ ] SQLite migration suite.
|
||||
- [ ] MySQL migration suite.
|
||||
- [ ] PostgreSQL migration suite.
|
||||
- [ ] OpenAPI schema check.
|
||||
- [ ] Custom Widget architecture and bundle-budget checks.
|
||||
- [ ] Workshop integration and image checks.
|
||||
- [ ] Container and E2E.
|
||||
- [ ] CodeQL for Actions, Go and JavaScript/TypeScript.
|
||||
- [ ] amd64 image build.
|
||||
- [ ] arm64 image build.
|
||||
- [ ] Multi-platform manifest publication.
|
||||
- [ ] Docs production build and link validation.
|
||||
- [ ] Production dependency audit and signed risk report.
|
||||
- [ ] All required checks are attached to the exact final SHA, not only an earlier `release/v2` SHA.
|
||||
|
||||
### Artifact integrity
|
||||
|
||||
- [ ] Produce and test `build-alpine-amd64.tar.gz`.
|
||||
- [ ] Produce and test `build-alpine-arm64.tar.gz`.
|
||||
- [ ] Produce and test `build-debian-amd64.tar.gz`.
|
||||
- [ ] Produce and test `build-debian-arm64.tar.gz`.
|
||||
- [ ] Publish SHA-256 checksums.
|
||||
- [ ] Generate/review an SBOM for production images and archives.
|
||||
- [ ] Decide and document signature/provenance verification.
|
||||
- [ ] Verify the archives and GHCR manifests originate from the same immutable release SHA.
|
||||
|
||||
## 11. Discord and community readiness
|
||||
|
||||
- [x] Confirm the `DISCORD_WEBHOOK` and `DISCORD_WEBHOOK_AUTOMATIC_RELEASE` secret names exist without exposing their
|
||||
values.
|
||||
- [ ] Confirm both webhook values still work; their name-level update timestamps are from 2024 and 2023 respectively.
|
||||
- [ ] Test release notifications in a non-public/test channel.
|
||||
- [ ] Prepare pre-release notice with date, expected impact, backup requirement and upgrade-guide link.
|
||||
- [ ] Brief moderators and support maintainers on breaking changes, migrations and rollback.
|
||||
- [ ] Prepare FAQ responses for permissions, layouts, Custom Widgets, Workshop, Assistant, MCP and databases.
|
||||
- [ ] Prepare success, delay, workflow-failure and rollback messages.
|
||||
- [ ] Review the prepared Discord copy in `apps/docs/release-announcements/2.0.0/discord.md` after merging the release
|
||||
article branch.
|
||||
- [ ] Prepare GitHub, Reddit and other community variants from the same verified claims.
|
||||
- [ ] Pin/update the relevant Discord channels and remove beta-only install instructions after GA.
|
||||
- [ ] Assign people to monitor Discord and GitHub for at least the first 24–48 hours.
|
||||
|
||||
## 12. Final go/no-go
|
||||
|
||||
### Candidate identity
|
||||
|
||||
- [ ] Final `dev` SHA: `________________________________________`.
|
||||
- [ ] Expected version: `v2.0.0`.
|
||||
- [ ] Homarr candidate manifest digest: `________________________________________`.
|
||||
- [ ] Workshop candidate manifest digest: `________________________________________`.
|
||||
- [ ] Database rehearsal evidence: `________________________________________`.
|
||||
- [ ] CI run: `________________________________________`.
|
||||
- [ ] Docs build/deploy evidence: `________________________________________`.
|
||||
- [ ] Security report/risk acceptance: `________________________________________`.
|
||||
- [ ] Rollback procedure: `________________________________________`.
|
||||
|
||||
### Sign-off
|
||||
|
||||
- [ ] Product acceptance owner: `________________` / date: `________________`.
|
||||
- [ ] Security owner: `________________` / date: `________________`.
|
||||
- [ ] Database owner: `________________` / date: `________________`.
|
||||
- [ ] Infrastructure owner: `________________` / date: `________________`.
|
||||
- [ ] Docs/communications owner: `________________` / date: `________________`.
|
||||
- [ ] Final release owner GO: `________________` / date: `________________`.
|
||||
- [ ] A rollback owner is online and the pre-upgrade backups are accessible.
|
||||
- [ ] No unchecked hard blocker remains without written acceptance.
|
||||
|
||||
## 13. Release-day execution
|
||||
|
||||
- [ ] Trigger or create the `dev -> main` release PR.
|
||||
- [ ] Verify the workflow proposes exactly `v2.0.0` and identifies a major bump.
|
||||
- [ ] Confirm the major PR did not auto-merge.
|
||||
- [ ] Recheck the PR diff, approvals, required checks and final candidate SHA.
|
||||
- [ ] Human-merge the PR into `main` during the release window.
|
||||
- [ ] Watch Semantic Release create the `v2.0.0` tag and draft release.
|
||||
- [ ] Watch amd64 and arm64 production image builds.
|
||||
- [ ] Watch all four release archives upload.
|
||||
- [ ] Watch `ghcr.io/homarr-labs/homarr:v2.0.0` publish.
|
||||
- [ ] Verify `ghcr.io/homarr-labs/homarr:latest` resolves to the same multi-platform manifest.
|
||||
- [ ] Verify the GitHub release is public, not draft/prerelease, and contains the curated notes and upgrade-guide link.
|
||||
- [ ] Download and smoke-test each release archive.
|
||||
- [ ] Verify image version and `/api/health` revision against the release SHA.
|
||||
- [ ] Verify the real deployed/runtime image digest, not only the registry tag.
|
||||
- [ ] Promote and verify Workshop production.
|
||||
- [ ] Verify public documentation and Algolia search.
|
||||
- [ ] Verify Discord/community announcements.
|
||||
- [ ] Verify post-release synchronization puts the Semantic Release commit back into `dev`.
|
||||
- [ ] Run a production smoke: sign-in, board load, widget query, integration query, WebSocket update, task, backup and
|
||||
Workshop browse/install.
|
||||
|
||||
## 14. Rollback triggers and execution
|
||||
|
||||
- [ ] Define rollback thresholds for startup failure, migration failure, authentication lockout, widespread blank
|
||||
boards, data loss, image failure and critical security regression.
|
||||
- [ ] Stop new writes if data integrity is uncertain.
|
||||
- [ ] Capture logs, exact image digest and database state before rollback.
|
||||
- [ ] Re-point `latest` only if the release owner invokes rollback.
|
||||
- [ ] Restore the pre-v2 database/appdata backup when v1 cannot read the migrated database.
|
||||
- [ ] Verify v1.76.2 health, authentication, boards, integrations and backups after rollback.
|
||||
- [ ] Publish the prepared rollback notice.
|
||||
- [ ] Keep `v2.0.0` artifacts/digests recorded for investigation; do not silently overwrite evidence.
|
||||
|
||||
## 15. Post-release follow-through
|
||||
|
||||
- [ ] Monitor release workflow, GHCR pulls, startup errors, migration errors and Workshop errors.
|
||||
- [ ] Monitor Discord, GitHub issues/discussions and support channels for 24–48 hours.
|
||||
- [ ] Maintain a public known-issues list.
|
||||
- [ ] Triage v2 reports separately from pre-existing v1 issues.
|
||||
- [ ] Prepare `v2.0.1` for fixes that are safer than rollback.
|
||||
- [ ] Remove or redirect `homarr-test:v2` and preview instructions when no longer needed.
|
||||
- [ ] Confirm beta users have a supported path to GA.
|
||||
- [ ] Close/repurpose the `v2.0.0` milestone.
|
||||
- [ ] Close obsolete stack branches and PRs after preserving history.
|
||||
- [ ] Hold a short retrospective covering integration drift, security backlog, CI failures, docs handoff and beta
|
||||
feedback.
|
||||
|
||||
## Refresh commands
|
||||
|
||||
Run these from a clean Homarr checkout. They are evidence helpers, not substitutes for reviewing the results.
|
||||
|
||||
```bash
|
||||
git fetch origin main dev release/v2 v2 next --tags --prune
|
||||
git show -s --format='%H %ci %s' origin/main origin/dev origin/release/v2
|
||||
git rev-list --left-right --count origin/dev...origin/release/v2
|
||||
git diff --shortstat origin/dev...origin/release/v2
|
||||
gh pr list --repo homarr-labs/homarr --state open --limit 100
|
||||
gh run list --repo homarr-labs/homarr --workflow deployment-weekly-release.yml --limit 10
|
||||
gh run list --repo homarr-labs/homarr --workflow deployment-docker-image.yml --limit 10
|
||||
gh release list --repo homarr-labs/homarr --limit 10
|
||||
mise exec -- pnpm audit --prod --audit-level high
|
||||
docker buildx imagetools inspect ghcr.io/homarr-labs/homarr-test:v2
|
||||
docker buildx imagetools inspect ghcr.io/homarr-labs/workshop:v2
|
||||
```
|
||||
|
||||
Never print secret values while collecting release evidence.
|
||||
The weekly workflow deliberately does not auto-merge major releases. A human must merge the final `dev -> main` PR
|
||||
after go/no-go approval.
|
||||
|
||||
## 1. Freeze `release/v2`
|
||||
|
||||
- [ ] Merge or explicitly defer #6765.
|
||||
- [ ] Merge or explicitly close #6790.
|
||||
- [ ] Confirm closing #6771 is intentional and mock integration behavior is safe for production.
|
||||
- [ ] Review every remaining open PR targeting `release/v2`; assign it `include`, `defer`, `superseded`, or `close`.
|
||||
- [ ] Stop non-release changes and record the frozen `release/v2` SHA: `________________`.
|
||||
- [ ] Record the release owner and the person authorized to approve risks: `________________`.
|
||||
|
||||
## 2. Promote `release/v2` to `dev`
|
||||
|
||||
- [ ] Create an integration branch from the current `dev` tip and merge the frozen `release/v2` into it.
|
||||
- [ ] Resolve all 43 conflict paths semantically; do not accept an entire side mechanically.
|
||||
- [ ] Review the 54 `dev`-only commits and preserve intentional fixes, translations, docs, CI, dependency, custom
|
||||
widget, MCP, auth, integration, and database changes.
|
||||
- [ ] Pay special attention to conflicts in workflows, dependency manifests and lockfiles, auth, MCP, integrations,
|
||||
server settings, database migrations, translations, docs navigation, and release documentation.
|
||||
- [ ] Confirm no migration, schema, workflow, or release configuration disappeared during conflict resolution.
|
||||
- [ ] Review the complete integration diff against both parents.
|
||||
- [ ] Open the promotion PR into `dev`; require human review and all required checks.
|
||||
- [ ] Merge the promotion PR and record the resulting `dev` SHA: `________________`.
|
||||
- [ ] Freeze that exact SHA as the final release candidate.
|
||||
|
||||
## 3. Validate the final candidate once
|
||||
|
||||
### Repository and build
|
||||
|
||||
- [ ] Install from the frozen lockfile in a clean environment.
|
||||
- [ ] Pass formatting, lint, typecheck, production build, unit tests, and the required E2E suite.
|
||||
- [ ] Pass docs and Workshop builds.
|
||||
- [ ] Confirm generated files, migrations, translation keys, and API schemas are current and committed.
|
||||
- [ ] Confirm no tracked build output, debug logging, test credentials, or temporary release files remain.
|
||||
|
||||
### Images and installation
|
||||
|
||||
- [ ] Build and publish candidate images for `linux/amd64` and `linux/arm64`.
|
||||
- [ ] Verify manifest architecture entries and record immutable digests.
|
||||
- [ ] Start the app from the candidate image with no outbound network access after the image pull.
|
||||
- [ ] Verify a clean install with the documented minimal configuration.
|
||||
- [ ] Verify supported Docker and Podman deployment paths, health checks, permissions, volumes, and graceful shutdown.
|
||||
|
||||
### Upgrade, data, backup, and rollback
|
||||
|
||||
- [ ] Upgrade representative `v1.76.2` SQLite, MySQL, and PostgreSQL instances to the candidate.
|
||||
- [ ] Verify migrations are idempotent, data is retained, and startup errors are actionable.
|
||||
- [ ] Create a backup using Homarr's backup tool before upgrading and restore it into a clean candidate instance.
|
||||
- [ ] Confirm restored users are prompted to sign in again and stale sessions cannot be reused.
|
||||
- [ ] Rehearse the documented rollback procedure, including database and volume restoration.
|
||||
- [ ] Record migration duration, storage requirements, and the last safe rollback point.
|
||||
|
||||
### Security and privacy
|
||||
|
||||
- [ ] Run the production dependency audit on the exact candidate and attach the report.
|
||||
- [ ] Require zero critical production advisories. Patch or explicitly accept every remaining high advisory.
|
||||
- [ ] Reconcile the two previously accepted image-processing highs with current upstream availability.
|
||||
- [ ] Pass CodeQL, secret scanning, image scanning, and repository security gates.
|
||||
- [ ] Verify auth, OIDC nested claims, API keys, permissions, CSRF, cookies, proxies, public origins, and MCP OAuth.
|
||||
- [ ] Confirm logs, telemetry, backups, exports, and errors do not expose credentials, tokens, or private user data.
|
||||
|
||||
### Product acceptance
|
||||
|
||||
- [ ] Smoke every primary route on desktop and mobile: login, onboarding, boards, search, management, settings, and
|
||||
error and empty states.
|
||||
- [ ] Create, edit, duplicate, import, export, share, and delete a board with representative widgets and layouts.
|
||||
- [ ] Verify all supported widget families, integration configuration, secrets, refresh behavior, errors, and recovery.
|
||||
- [ ] Verify users, groups, permissions, home boards, API keys, OIDC, and proxy-auth flows.
|
||||
- [ ] Verify Custom Widgets, Workshop, Assistant, MCP, uploads, icons, image proxying, downloads, and backups.
|
||||
- [ ] Verify tasks, cron jobs, WebSocket updates, Redis behavior, notifications, and background recovery.
|
||||
- [ ] Recheck the release fixes for UniFi ports, Nextcloud subpaths, Docker CPU usage, Unraid memory units, disabled
|
||||
external weather connections, public MCP OAuth origin, and download-name sizing.
|
||||
- [ ] Run at least one real-provider happy path and failure path for every production-critical integration family.
|
||||
- [ ] Confirm accessibility basics: keyboard use, focus, dialogs, labels, contrast, zoom, and reduced motion.
|
||||
- [ ] Confirm no blocker or release-critical issue remains; link accepted known issues.
|
||||
|
||||
## 4. Finish documentation and communication
|
||||
|
||||
- [ ] Complete the #6790 decision and ensure the final release article matches the shipped candidate.
|
||||
- [ ] Before publishing, set the v2 article out of draft and remove its editorial release-gate placeholder.
|
||||
- [ ] Replace branch comparisons and preview references with the final `v2.0.0` tag, image, and URLs.
|
||||
- [ ] Keep the v1-to-v2 upgrade guide direct: create a backup in Homarr's backup tool, store it somewhere safe, then
|
||||
follow the supported image and migration steps.
|
||||
- [ ] Verify environment examples contain no real domains, secrets, tokens, passwords, or unsafe defaults.
|
||||
- [ ] Update Helm documentation to the actually published v2 chart version and image tag.
|
||||
- [ ] Search code, docs, workflows, examples, metadata, and translations for `TODO`, `FIXME`, placeholder text, demo
|
||||
credentials, stale v1 copy, preview domains, and old image tags; resolve or explicitly accept every match.
|
||||
- [ ] Build the docs, run link checks, inspect screenshots and navigation, and verify search indexing.
|
||||
- [ ] Prepare concise release notes, breaking changes, upgrade steps, known issues, and rollback link.
|
||||
- [ ] Prepare the Discord announcement, support channels, moderator brief, FAQ, and incident owner.
|
||||
|
||||
## 5. Prove CI and deployment readiness
|
||||
|
||||
- [ ] Revalidate the restored release automation from #6770 on the final workflow files.
|
||||
- [ ] Verify weekly `dev -> main` behavior, including the no-change path and the intentional no-auto-merge rule for a
|
||||
major release.
|
||||
- [ ] Fix or explicitly justify any workflow still matching `refs/heads/v2` instead of `release/v2`.
|
||||
- [ ] Verify required checks and branch protection for `release/v2`, `dev`, and `main`.
|
||||
- [ ] Verify release tokens, signing/provenance, package permissions, GHCR access, and both Discord webhooks without
|
||||
exposing secret values.
|
||||
- [ ] Put the production release behind an environment with the intended human approval and rollback authority.
|
||||
- [ ] Rehearse Semantic Release in dry-run mode and confirm it selects `v2.0.0` with the intended changelog.
|
||||
- [ ] Verify GitHub release assets, source archives, multi-architecture GHCR tags, immutable digests, docs deployment,
|
||||
and Workshop deployment from the candidate.
|
||||
- [ ] Confirm the production image contains no preview-only configuration and installs without GitHub credentials.
|
||||
|
||||
## 6. Go/no-go
|
||||
|
||||
- [ ] Release owner: `________________`
|
||||
- [ ] Incident and rollback owner: `________________`
|
||||
- [ ] Release window and support coverage: `________________`
|
||||
- [ ] Final candidate SHA: `________________`
|
||||
- [ ] Homarr image digest: `________________`
|
||||
- [ ] Workshop image digest: `________________`
|
||||
- [ ] All blockers are closed or have written acceptance linked here: `________________`
|
||||
- [ ] Engineering, QA, security, docs, operations, and community owners have signed off.
|
||||
- [ ] A rollback checkpoint, command sequence, and decision threshold are documented and rehearsed.
|
||||
- [ ] The `dev -> main` PR contains only the approved candidate and has the required approvals and checks.
|
||||
|
||||
## 7. Release and verify
|
||||
|
||||
- [ ] Human-merge the approved `dev -> main` PR.
|
||||
- [ ] Verify Semantic Release creates the `v2.0.0` tag and GitHub release from the approved SHA.
|
||||
- [ ] Verify release assets and multi-architecture `v2.0.0` and `latest` image tags resolve to approved digests.
|
||||
- [ ] Perform clean-install and v1-upgrade smoke tests using only public production instructions and artifacts.
|
||||
- [ ] Verify production docs, release article, upgrade guide, links, search, Workshop, and downloads.
|
||||
- [ ] Publish the Discord announcement only after public artifacts have passed smoke tests.
|
||||
- [ ] Monitor startup failures, migrations, auth, integrations, jobs, image pulls, docs, support, and security signals.
|
||||
- [ ] Roll back immediately if data integrity, upgrade safety, auth, or broad installation is compromised.
|
||||
|
||||
## 8. Post-release
|
||||
|
||||
- [ ] Triage incoming reports and publish known issues or hotfix guidance quickly.
|
||||
- [ ] Confirm no regression after the first scheduled tasks, backups, and weekly automation cycle.
|
||||
- [ ] Close or move the v2 milestone and deferred PRs with explicit follow-up destinations.
|
||||
- [ ] Record final SHAs, digests, evidence, accepted risks, incidents, and retrospective actions.
|
||||
- [ ] Remove temporary release freezes, preview resources, and obsolete compatibility paths only after stability is
|
||||
confirmed.
|
||||
|
||||
## Evidence record
|
||||
|
||||
| Gate | Owner | Evidence | Result |
|
||||
| --- | --- | --- | --- |
|
||||
| Promotion merge | | | |
|
||||
| CI and build | | | |
|
||||
| Images and install | | | |
|
||||
| Migration and rollback | | | |
|
||||
| Security | | | |
|
||||
| Product acceptance | | | |
|
||||
| Docs and communication | | | |
|
||||
| Production smoke | | | |
|
||||
Reference in new issue
Block a user