feat: add release communications
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
# Task: Backend release update foundation
|
||||
|
||||
## Goal
|
||||
|
||||
Add the backend foundation for curated release update entries and per-user read state.
|
||||
|
||||
## Feature Spec
|
||||
|
||||
- `docs/FEATURES/release-communications.md`
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a new FastEndpoints module under `backend/src/Socialize.Api/Modules/ReleaseCommunications`.
|
||||
- Add release update data entities and EF Core model configuration.
|
||||
- Add per-user release update read receipts.
|
||||
- Add enum/value support for:
|
||||
- category: `Feature`, `Improvement`, `Fix`, `BreakingChange`
|
||||
- importance: `Normal`, `Important`
|
||||
- audience: `Everyone`, `OrganizationOwners`, `Developers`
|
||||
- status: `Draft`, `Published`, `Archived`
|
||||
- Add `DbSet` entries and module configuration to `AppDbContext`.
|
||||
- Add current-user API endpoints:
|
||||
- list visible published release updates
|
||||
- get unread visible release updates
|
||||
- mark one release update as read
|
||||
- mark all visible release updates as read
|
||||
- Add developer API endpoints:
|
||||
- list all release updates
|
||||
- create draft release update
|
||||
- get release update detail
|
||||
- update draft release update
|
||||
- publish release update
|
||||
- archive release update
|
||||
- Enforce access rules:
|
||||
- authenticated users can read only visible published updates
|
||||
- only `Developer` users can manage update entries
|
||||
- organization-owner audience only appears to users who own at least one organization
|
||||
- developer audience only appears to `Developer` users
|
||||
- Keep commit import and email digest out of this task.
|
||||
|
||||
## Likely Files
|
||||
|
||||
- `backend/src/Socialize.Api/Data/AppDbContext.cs`
|
||||
- `backend/src/Socialize.Api/Modules/ReleaseCommunications/**`
|
||||
- `backend/tests/Socialize.Tests/**`
|
||||
|
||||
## Notes
|
||||
|
||||
- Treat release communications as global SaaS operator data, not workspace-owned workflow data.
|
||||
- Use FastEndpoints handlers and keep request/response records near handlers unless local module patterns suggest otherwise.
|
||||
- Use FluentValidation for non-trivial input.
|
||||
- Do not expose draft entries to non-developer users.
|
||||
- Do not expose commit metadata in user-facing DTOs.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
dotnet build backend/Socialize.slnx
|
||||
dotnet test backend/Socialize.slnx
|
||||
```
|
||||
|
||||
## Done When
|
||||
|
||||
- [x] Developers can create draft release update entries.
|
||||
- [x] Developers can publish and archive release updates.
|
||||
- [x] Authenticated users can list visible published updates.
|
||||
- [x] Audience filtering is enforced.
|
||||
- [x] Users can mark one update read.
|
||||
- [x] Users can mark all visible updates read.
|
||||
- [x] Unread queries only count visible published updates.
|
||||
- [x] Backend tests cover access rules and read state.
|
||||
54
docs/TASKS/release-communications/002-frontend-whats-new.md
Normal file
54
docs/TASKS/release-communications/002-frontend-whats-new.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Task: Frontend What’s New experience
|
||||
|
||||
## Goal
|
||||
|
||||
Add the user-facing What’s New experience for published release updates and unread state.
|
||||
|
||||
## Feature Spec
|
||||
|
||||
- `docs/FEATURES/release-communications.md`
|
||||
|
||||
## Scope
|
||||
|
||||
- Add feature-owned frontend code under `frontend/src/features/release-communications/`.
|
||||
- Add `/app/updates`.
|
||||
- Add an app shell entry or badge for unread release updates.
|
||||
- Fetch visible published release updates from the backend.
|
||||
- Show unread state for update entries.
|
||||
- Mark an update as read when opened.
|
||||
- Add a mark-all-read action.
|
||||
- Optionally show a non-blocking login-time What’s New panel when unread updates exist.
|
||||
- Add English and French locale strings.
|
||||
- Keep developer authoring UI, commit reconciliation, and email digest out of this task.
|
||||
|
||||
## Likely Files
|
||||
|
||||
- `frontend/src/router/router.js`
|
||||
- `frontend/src/layouts/main/**`
|
||||
- `frontend/src/features/release-communications/**`
|
||||
- `frontend/src/locales/en.json`
|
||||
- `frontend/src/locales/fr.json`
|
||||
|
||||
## Notes
|
||||
|
||||
- The user-facing update feed must be curated and should not show raw commit SHAs, commit subjects, branch names, or internal-only work.
|
||||
- Keep the UI compact and app-like. This is an operational app surface, not a marketing release notes page.
|
||||
- Use the shared Axios API client in `frontend/src/plugins/api.js`.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Done When
|
||||
|
||||
- [x] Authenticated users can open `/app/updates`.
|
||||
- [x] The app shell shows unread update count.
|
||||
- [x] Published visible updates are listed newest first.
|
||||
- [x] Unread updates are visually distinct.
|
||||
- [x] Opening an update marks it read.
|
||||
- [x] Users can mark all visible updates read.
|
||||
- [x] UI strings exist in English and French.
|
||||
- [x] Frontend build passes.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Task: Developer commit reconciliation
|
||||
|
||||
## Goal
|
||||
|
||||
Add the developer back-office workflow for importing shipped commits and matching them to curated release update entries.
|
||||
|
||||
## Feature Spec
|
||||
|
||||
- `docs/FEATURES/release-communications.md`
|
||||
|
||||
## Scope
|
||||
|
||||
- Add release commit persistence and EF Core model configuration.
|
||||
- Add enum/value support for communication status:
|
||||
- `Unreviewed`
|
||||
- `Linked`
|
||||
- `InternalOnly`
|
||||
- `Ignored`
|
||||
- Add developer API endpoints:
|
||||
- list imported commits
|
||||
- import commits for a bounded range
|
||||
- link a commit to a release update
|
||||
- unlink a commit from a release update
|
||||
- mark a commit internal-only
|
||||
- mark a commit ignored
|
||||
- Add developer-only frontend screens:
|
||||
- `/app/developer/release-commits`
|
||||
- linked commits on `/app/developer/updates/:id`
|
||||
- Support filters for:
|
||||
- communication status
|
||||
- linked update
|
||||
- author
|
||||
- date range
|
||||
- text search by subject or SHA
|
||||
- Show an unreviewed commit count.
|
||||
- Keep user-facing update views free of commit metadata.
|
||||
- Keep automatic CI deployment integration out of this task.
|
||||
|
||||
## Likely Files
|
||||
|
||||
- `backend/src/Socialize.Api/Data/AppDbContext.cs`
|
||||
- `backend/src/Socialize.Api/Modules/ReleaseCommunications/**`
|
||||
- `frontend/src/router/router.js`
|
||||
- `frontend/src/layouts/main/**`
|
||||
- `frontend/src/features/release-communications/**`
|
||||
- `frontend/src/locales/en.json`
|
||||
- `frontend/src/locales/fr.json`
|
||||
- `backend/tests/Socialize.Tests/**`
|
||||
|
||||
## Notes
|
||||
|
||||
- Commit import must be idempotent by SHA.
|
||||
- A commit can be linked to at most one release update in v1.
|
||||
- A release update can have many linked commits.
|
||||
- Imported commits default to `Unreviewed`.
|
||||
- Import must use either a submitted commit payload or configured repository connection settings. Do not discover or read a local `.git` directory from the deployed app filesystem.
|
||||
- Repository URL and access credentials must come from configuration/secrets.
|
||||
- Do not generate user-facing update entries automatically from commits.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
dotnet build backend/Socialize.slnx
|
||||
dotnet test backend/Socialize.slnx
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Done When
|
||||
|
||||
- [x] Developers can import commits idempotently.
|
||||
- [x] Developers can list and filter imported commits.
|
||||
- [x] Developers can link commits to release updates.
|
||||
- [x] Developers can unlink commits.
|
||||
- [x] Developers can mark commits internal-only.
|
||||
- [x] Developers can mark commits ignored.
|
||||
- [x] Release update detail shows linked commits to developers.
|
||||
- [x] Unreviewed commit count is visible to developers.
|
||||
- [x] Non-developer users cannot access commit reconciliation APIs or UI.
|
||||
- [x] User-facing update views do not expose commit metadata.
|
||||
70
docs/TASKS/release-communications/004-email-digest.md
Normal file
70
docs/TASKS/release-communications/004-email-digest.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# Task: Release update email digest
|
||||
|
||||
## Goal
|
||||
|
||||
Add optional daily email digests for inactive users with unread release updates, plus a developer-operated manual email push for important published updates.
|
||||
|
||||
## Feature Spec
|
||||
|
||||
- `docs/FEATURES/release-communications.md`
|
||||
|
||||
## Scope
|
||||
|
||||
- Add configuration to enable or disable release update email digests.
|
||||
- Add persistence needed to rate-limit digest sends per user.
|
||||
- Send at most one digest per user per day.
|
||||
- Send only when the user has unread visible published release updates.
|
||||
- Send only when the user has not logged in or opened the app in at least 24 hours.
|
||||
- Initially target organization owners.
|
||||
- Use the existing email infrastructure.
|
||||
- Add a developer-only API endpoint to send an email announcement for a selected published release update.
|
||||
- Add a developer-only back-office button for sending the selected update by email.
|
||||
- Require confirmation before sending a manual push email.
|
||||
- Support a "send to me only" test mode.
|
||||
- Record manual push email metadata:
|
||||
- sent by user id
|
||||
- sent timestamp
|
||||
- selected audience
|
||||
- recipient count
|
||||
- Prevent accidental duplicate push sends unless the developer explicitly confirms a resend.
|
||||
- Keep user or organization email preferences out of this task.
|
||||
|
||||
## Likely Files
|
||||
|
||||
- `backend/src/Socialize.Api/Infrastructure/Emailer/**`
|
||||
- `backend/src/Socialize.Api/Modules/ReleaseCommunications/**`
|
||||
- `backend/src/Socialize.Api/Modules/Identity/**`
|
||||
- `backend/src/Socialize.Api/Modules/Organizations/**`
|
||||
- `frontend/src/features/release-communications/**`
|
||||
- `frontend/src/locales/en.json`
|
||||
- `frontend/src/locales/fr.json`
|
||||
- `backend/tests/Socialize.Tests/**`
|
||||
|
||||
## Notes
|
||||
|
||||
- This task may require tracking a user's last app activity timestamp if login timestamp alone is not enough.
|
||||
- Keep email copy concise and product-specific.
|
||||
- The digest should link back to the app's What’s New page.
|
||||
- Manual push emails should link directly to the selected update when possible.
|
||||
- Do not introduce a new email provider.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
dotnet build backend/Socialize.slnx
|
||||
dotnet test backend/Socialize.slnx
|
||||
```
|
||||
|
||||
## Done When
|
||||
|
||||
- [x] Digest delivery is disabled unless explicitly configured.
|
||||
- [x] Eligible organization owners receive at most one digest per day.
|
||||
- [x] Digests are sent only when unread visible release updates exist.
|
||||
- [x] Active users are not emailed.
|
||||
- [x] Developers can manually send a published update email from the back office.
|
||||
- [x] Developers can send a manual update email to themselves as a test.
|
||||
- [x] Manual push sends require confirmation.
|
||||
- [x] Manual push sends record sender, timestamp, audience, and recipient count.
|
||||
- [x] Duplicate manual sends require explicit resend confirmation.
|
||||
- [x] Email delivery uses existing email infrastructure.
|
||||
- [x] Backend tests cover eligibility and rate limiting.
|
||||
Reference in New Issue
Block a user