Add project documentation and update workflow plan

Adds AGENTS.md, DESIGN.md, and docs/* covering architecture, conventions, decisions, checklists, branching, release process, and prompts. Updates README and workflow-feedback-plan to reflect the decoupled GroupName nomination model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-28 23:31:13 +02:00
parent 18b61bed52
commit fc5c13a4fd
13 changed files with 1670 additions and 15 deletions
@@ -0,0 +1,99 @@
+# Release Process
+
+This document defines release expectations for VTuber Star Awards.
+
+For daily delivery flow, see [workflow.md](workflow.md). For branch policy, see
+[branching.md](branching.md). For release checklist, see
+[CHECKLISTS.md](CHECKLISTS.md#release).
+
+## Release Principles
+
+- Keep releases small when practical.
+- Prefer repeatable automation over manual server edits.
+- Validate before and after deployment.
+- Review migration and configuration risk before deploy.
+- Keep rollback or recovery options ready.
+
+## Release Types
+
+| Type | Description |
+| --- | --- |
+| Standard | Planned change deployed from `main` through the Gitea workflow. |
+| Hotfix | Urgent production correction with the smallest safe change. |
+| Documentation-only | Docs update that does not require runtime deployment validation. |
+| Infrastructure | Runtime, hosting, Docker, database, network, or secret/config change. |
+
+## Versioning
+
+The frontend package version lives in `frontend/package.json`. The deploy
+workflow appends build metadata and writes `VITE_BUILD_VERSION` plus
+`VITE_BUILD_DATE` before building production assets.
+
+## Readiness
+
+Before releasing application changes:
+
+- frontend build passes;
+- backend Release build passes;
+- `git diff --check` passes;
+- migration operations are reviewed;
+- target environment config and secrets are present;
+- demo, seed, CORS, and production safety settings are understood;
+- UI or API behavior has targeted validation evidence.
+
+## Automated Deployment
+
+The production deploy job in `.gitea/workflows/ci.yaml` runs on `main` pushes
+and manual dispatches.
+
+Pipeline responsibilities:
+
+1. Verify repository hygiene.
+2. Build backend and frontend.
+3. Resolve version/build metadata.
+4. Verify production host layout.
+5. Sync repository contents to the production app directory.
+6. Write frontend build metadata.
+7. Build Docker images.
+8. Write a PostgreSQL predeploy backup.
+9. Apply EF Core migrations.
+10. Recreate `api` and `web` services.
+11. Verify API health, database connectivity, pending migrations, and frontend
+    assets.
+
+## Smoke Tests
+
+Minimum automated smoke signals:
+
+- `https://award.noveria.net/api/health`
+- `https://award.noveria.net/api/health/database`
+- `pendingMigrations` is empty;
+- frontend index serves current JS and CSS assets;
+- JS asset contains expected build version metadata.
+
+Add manual smoke checks for the changed workflow, especially for admin,
+auth/permissions, voting, nomination, clip review, showact, sponsor, or content
+management changes.
+
+## Rollback And Recovery
+
+Rollback planning should address:
+
+- application artifact rollback or redeploy from a previous commit;
+- database restore or forward-fix path;
+- configuration rollback;
+- disabling demo/seed/optional public features;
+- communication of degraded public workflows.
+
+If a migration is destructive or hard to reverse, document the recovery path
+before deployment.
+
+## Post-Release Review
+
+After production-impacting releases:
+
+- confirm health checks and relevant public/admin workflows;
+- check for unexpected database migration state;
+- record incidents or anomalies;
+- update docs, checklists, or ADRs when release steps drift;
+- add follow-up tests or runbooks for gaps found during release.