From b82cdd1b0bf7f8bc8a14e56a117b237bf7d7651f Mon Sep 17 00:00:00 2001 From: ajnart Date: Sun, 6 Sep 2026 09:32:10 +0200 Subject: [PATCH] docs: add Homarr v2 release checklist --- docs/V2_RELEASE_CHECKLIST.md | 612 +++++++++++++++++++++++++++++++++++ 1 file changed, 612 insertions(+) create mode 100644 docs/V2_RELEASE_CHECKLIST.md diff --git a/docs/V2_RELEASE_CHECKLIST.md b/docs/V2_RELEASE_CHECKLIST.md new file mode 100644 index 000000000..434c049fa --- /dev/null +++ b/docs/V2_RELEASE_CHECKLIST.md @@ -0,0 +1,612 @@ +# Homarr v2 GA release checklist + +Last audited: 2026-09-06 (Europe/Berlin) + +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. + +## Release path + +```text +release/v2 + -> reviewed integration branch based on current dev + -> promotion PR into dev + -> final candidate validation on dev + -> weekly or manually-created dev -> main PR + -> HUMAN merge for the v2 major release + -> Semantic Release creates v2.0.0 + -> GitHub release + GHCR images + release 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 11 content conflicts. +- [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. +- [ ] 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. + +### Current merge conflicts + +- [ ] `.gitignore` +- [ ] `apps/docs/docs/getting-started/installation/helm.md` +- [ ] `apps/docs/docs/widgets/smart-home-entity-state/index.mdx` +- [ ] `apps/docs/docs/widgets/smart-home-execute-automation/index.mdx` +- [ ] `e2e/onboarding.spec.ts` +- [ ] `packages/api/src/router/widgets/smart-home.ts` +- [ ] `packages/integrations/src/truenas/test/truenas-integration.spec.ts` +- [ ] `packages/translation/src/lang/et.json` +- [ ] `packages/translation/src/lang/fr.json` +- [ ] `packages/translation/src/lang/no.json` +- [ ] `packages/translation/src/lang/ro.json` + +## Current hard blockers + +- [ ] **BLOCKER — integrate histories:** reconcile all 54 `dev`-only commits and resolve the 11 current merge + conflicts without dropping either branch's behavior. +- [ ] **BLOCKER — production dependency audit:** `mise exec -- pnpm audit --prod --audit-level high` currently exits + with 141 findings: 4 critical, 65 high, 62 moderate and 10 low. +- [ ] **BLOCKER — direct authentication advisories:** upgrade or explicitly accept the critical `next-auth` and + `@auth/core` findings. The candidate currently resolves `next-auth@5.0.0-beta.31` and `@auth/core@0.41.2`. +- [ ] **BLOCKER — weekly promotion automation:** the last two scheduled weekly release runs failed in `Get Next + Version` with `No commit resulted in a version bump since last release!`. Make the no-release case a clean skip. +- [ ] **BLOCKER — scheduled notifications:** scheduled weekly notifications and the failure notification are skipped + because they depend on `github.event.inputs.send-notifications`, which is absent for schedule events. +- [ ] **BLOCKER — documentation release:** Homarr's release workflow dispatches `homarr-labs/documentation`, but that + repository's active release workflow only installs dependencies and echoes that it acknowledged the tag. It does not + build or deploy documentation. +- [ ] **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 — final upgrade rehearsal:** perform backup, migration, restore and rollback rehearsals from real + `v1.76.2` installations for SQLite, MySQL and PostgreSQL. +- [ ] **BLOCKER — upgrade guide:** publish one canonical v1-to-v2 guide covering breaking changes, backups, + migrations, rollback limits, changed configuration and supported installation paths. +- [ ] **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:** disable mock integrations in `.env.example` and verify server-side creation + cannot bypass `UNSAFE_ENABLE_MOCK_INTEGRATION`. +- [ ] **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. +- [ ] [#6624 backup restore re-login](https://github.com/homarr-labs/homarr/pull/6624) — verify whether the final v2 + candidate already contains the intended redirect and user warning. Port the minimal fix if not; do not merge its + unrelated branch drift wholesale. +- [ ] [#6631 MCP OAuth base URL](https://github.com/homarr-labs/homarr/pull/6631) — security and reverse-proxy + relevance; include/port or document why it is safe to defer. +- [ ] [#6662 board access-control form](https://github.com/homarr-labs/homarr/pull/6662) — permission correctness; + include/port or explicitly defer. +- [ ] [#6674 weather and `NO_EXTERNAL_CONNECTION`](https://github.com/homarr-labs/homarr/pull/6674) — offline/privacy + contract; include/port or explicitly defer. +- [ ] [#6749 Unraid memory utilization](https://github.com/homarr-labs/homarr/pull/6749) — validate against the v2 + system widgets and include/port or defer. +- [ ] [#6250 container CPU utilization](https://github.com/homarr-labs/homarr/pull/6250) — recently updated and + potentially user-visible for v2 Docker widgets; include/port or defer. +- [ ] [#6733 Helm documentation](https://github.com/homarr-labs/homarr/pull/6733) — reconcile with the v2 Helm + conflict and current chart; do not ship competing instructions. +- [ ] [#6601 broad dependency update](https://github.com/homarr-labs/homarr/pull/6601) — do not merge wholesale just + to clear advisories; create a focused security upgrade if this PR is too broad or stale. + +### Feature/UI candidates to include or defer explicitly + +- [ ] #6657 OMV volume selection +- [ ] #6645 Beszel GPU metrics +- [ ] #6621 Downloads column width +- [ ] #6603 isolated pnpm linker/phantom dependencies +- [ ] #6572 Hermes Agent integration +- [ ] #6562 favicon detection +- [ ] #6561 Komodo integration +- [ ] #6546 REST dashboard automation +- [ ] #6537 dashboard memory work +- [ ] #6518 Sportarr integration +- [ ] #6517 UGOS integration +- [ ] #6515 SABnzbd archived-history options +- [ ] #6458 API add-item section targeting +- [ ] #6393 board keyboard shortcuts +- [ ] #6295 Nextcloud subpath fix +- [ ] #6294 nested OIDC claims +- [ ] #6210 UniFi default ports +- [ ] #6148 path-only app URLs + +### 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`. +- [ ] Resolve/close #6549, whose head and base are both `dev`. +- [ ] Close superseded duplicate PRs such as the older Downloads-width and path-only URL variants. +- [ ] 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`. +- [ ] Rebase `origin/feat/homarr-v2-release-blog` onto current `release/v2`; it is currently two commits behind and + nine ahead. +- [ ] Review and merge the Homarr 2.0 blog, screenshots/GIFs, and GitHub/Reddit/Discord announcement variants from + that branch. +- [ ] Confirm no release-research scratch material is published unintentionally. + +## 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. +- [ ] Upgrade `@auth/core` to a patched release and validate every authentication provider. +- [ ] Upgrade `next-auth` to a patched release and validate failure-open, email normalization and session behavior. +- [ ] Resolve or accept the critical `protobufjs` path after separating runtime use from testcontainer tooling. +- [ ] Resolve or accept the critical `handlebars` path after identifying whether it enters any production artifact. +- [ ] Triage high findings including `undici`, `adm-zip`, `fast-xml-parser`, `axios`, `hono`, `postcss`, + `serialize-javascript`, `image-size`, `fast-uri`, `js-yaml`, `brace-expansion`, `find-my-way`, `immutable`, `svgo`, + `shell-quote`, `@xmldom/xmldom`, `protobufjs` and `handlebars`. +- [ ] 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 — correlate with #6616 and retest 13/23/24-column layouts. +- [ ] Incorrect v1.74 update indicator in the v2 preview — verify final image reports v2.0.0 and no false update. +- [ ] Full-page widget refresh reported as roughly 5 seconds in v1 versus 72 seconds in v2 — reproduce and profile. +- [ ] Date/time widget missing world clocks — reproduce and close or fix. +- [ ] Media Releases widget reported non-functional — reproduce with supported providers and close or fix. +- [ ] Compact bookmarks reported as not compact — #6747 is present; visually retest all supported sizes. +- [ ] 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 + +- [ ] Publish a 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 + +- [ ] Update `.github/pull_request_template.md`; it still tells contributors to open documentation changes in the + separate `homarr-labs/documentation` repository even though docs live in this monorepo. +- [ ] Decide whether to restore a root `README.md`. Only `docs/README.md` currently exists. +- [ ] Fix the seven generated `href="null"` integration links in `docs/README.md` and make the generator omit or + safely handle integrations without a documentation URL. +- [ ] Replace `.env.example`'s `DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'` with a safe runnable example or clearly + commented unset value. +- [ ] Set `UNSAFE_ENABLE_MOCK_INTEGRATION=false` or comment it out in `.env.example`. +- [ ] Verify direct URLs/API calls cannot create a mock integration when the unsafe flag is disabled. +- [ ] Review sample `AUTH_SECRET` and encryption keys so no example can be mistaken for production-safe material. +- [ ] 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 + +- [ ] Make the weekly workflow exit successfully with a clear `no releasable change` result when Semantic Versioning + finds no bump. +- [ ] Fix notification conditions so scheduled runs notify by default and manual runs respect the 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. +- [ ] Replace the downstream documentation acknowledgement workflow with an actual build/deploy or remove the false + release handoff and make monorepo docs deployment authoritative. +- [ ] Add an explicit production deployment failure notification. +- [ ] Remove `continue-on-error` from post-release `dev` synchronization, or add a mandatory job that verifies `dev` + contains the Semantic Release commit and fails loudly otherwise. +- [ ] 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 + +- [ ] Confirm `DISCORD_WEBHOOK` and `DISCORD_WEBHOOK_AUTOMATIC_RELEASE` exist and work without exposing their values. +- [ ] 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.