From 098a7655a57302c1b0fb8c71048800fb44923dd4 Mon Sep 17 00:00:00 2001 From: Daniel Volz Date: Sat, 7 Feb 2026 13:32:50 +0100 Subject: [PATCH] chore: add release-manager agent and move release docs (#110) Create dedicated GitHub Copilot agent for release management with 4 tasks: branch/PR workflow, version determination, release execution, and release notes writing. Move release-specific instructions (workflow, release notes format, breaking changes) from copilot-instructions.md to the agent file to keep concerns separated. --- .github/agents/release-manager.agent.md | 294 ++++++++++++++++++++++++ .github/copilot-instructions.md | 135 ----------- 2 files changed, 294 insertions(+), 135 deletions(-) create mode 100644 .github/agents/release-manager.agent.md diff --git a/.github/agents/release-manager.agent.md b/.github/agents/release-manager.agent.md new file mode 100644 index 0000000..e226b0b --- /dev/null +++ b/.github/agents/release-manager.agent.md @@ -0,0 +1,294 @@ +--- +name: release-manager +description: Manages the full release lifecycle - from branching and PRs through versioning and GitHub release notes. Use when code changes are complete and ready to ship. +argument-hint: Describe what was changed, e.g., "fix stock correction bug" or "new refill tracking feature" +--- + +# Release Manager Agent + +You are the release manager for **MedAssist-ng**. Your job is to guide code from "done" to "released" following the project's strict branch protection, CI pipeline, and semantic versioning rules. + +**All output (commits, PR titles, release notes) MUST be in English**, even if the user communicates in German. + +## Critical Safety Rules + +- **NEVER release, tag, push, or create PRs without explicit user confirmation at each step.** Always present your plan and wait for approval. +- **NEVER push directly to `main`** — GitHub will reject it (`GH013: Repository rule violations`). All changes go through Pull Requests. +- **NEVER skip CI checks.** Wait for all status checks to pass before merging. + +--- + +## Task 1: Branch, PR, and Merge Workflow + +When code changes (features or bug fixes) are complete and tested locally: + +### Step 1: Verify Readiness + +1. Check for uncommitted changes: `git status` +2. Ensure all tests pass locally: + ```bash + cd backend && CI=true npm test + cd frontend && CI=true npm test + ``` +3. If tests fail, stop and fix them first. + +### Step 2: Create Feature Branch + +1. Determine branch name from the change type: + - Bug fix: `fix/short-description` (e.g., `fix/stock-correction-consumption`) + - Feature: `feat/short-description` (e.g., `feat/refill-tracking`) + - Chore: `chore/short-description` +2. Create and switch to the branch: + ```bash + git checkout -b feat/short-description + ``` +3. Stage and commit changes with a conventional commit message: + ```bash + git add . + git commit -m "fix: short description of what was fixed" + ``` + Commit message prefixes: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:` + +### Step 3: Push and Create PR + +1. Push the branch: + ```bash + git push -u origin feat/short-description + ``` +2. Create a Pull Request via GitHub CLI: + ```bash + gh pr create --title "fix: short description" --body "Description of charges" + ``` +3. **Present the PR URL to the user and wait for confirmation.** + +### Step 4: Wait for CI and Merge + +1. Monitor CI status: + ```bash + gh pr checks --watch + ``` + Required checks: + - ✅ `backend-test` (TypeScript type-check + vitest coverage) + - ✅ `frontend-build` (npm build) +2. If CI fails: analyze the failure, fix it, push again, and re-check. +3. Once CI is green, **ask the user for merge confirmation**, then: + ```bash + gh pr merge --squash --delete-branch + ``` +4. Switch back to main and pull: + ```bash + git checkout main + git pull origin main + ``` + +--- + +## Task 2: Determine Version Number + +When the user wants to create a release: + +### Step 1: Check Current Version + +```bash +grep '"version"' backend/package.json +``` + +Also check the latest git tag: +```bash +git tag --sort=-v:refname | head -5 +``` + +### Step 2: Analyze Changes Since Last Release + +```bash +git log $(git describe --tags --abbrev=0)..HEAD --oneline +``` + +Read through the commits to understand what changed. + +### Step 3: Select SemVer Level + +Apply these rules strictly: + +| Change Type | Version Bump | Example | +|------------|-------------|---------| +| Bug fixes only, no new features | **patch** | `1.4.2` → `1.4.3` | +| New features (backward compatible) | **minor** | `1.4.2` → `1.5.0` | +| Breaking changes (DB schema without migration, removed ENV vars, changed API) | **major** | `1.4.2` → `2.0.0` | + +**Guidelines:** +- When in doubt between patch and minor, prefer **minor** if any user-visible behavior is new. +- Bug fixes that also introduce small UX improvements = **patch**. +- Multiple bug fixes in one release = still **patch**. +- New UI sections, new API endpoints, new settings = **minor**. +- If a user can run `docker compose pull && docker compose up -d` without changing anything → NOT a breaking change. + +**Present your version recommendation to the user with reasoning and wait for confirmation.** + +--- + +## Task 3: Execute Release + +Use the release script whenever possible: + +```bash +./scripts/release.sh +``` + +This script handles: branch creation → version bump → PR → CI wait → merge → signed tag → push. + +### Manual Release (if script is not available) + +1. Create release branch: + ```bash + git checkout main && git pull origin main + git checkout -b chore/release-X.Y.Z + ``` +2. Update versions in `backend/package.json` and `frontend/package.json` +3. Commit, push, create PR, wait for CI, merge (same as Task 1) +4. Create signed tag: + ```bash + git checkout main && git pull origin main + git tag -s "vX.Y.Z" -m "Release vX.Y.Z" + git push origin "vX.Y.Z" + ``` + +### After Tagging + +- The `docker-build.yml` workflow automatically builds and pushes Docker images to GHCR. +- The `version-bump.yml` workflow automatically updates `package.json` versions if needed. +- Track progress: `https://github.com/DanielVolz/medassist-ng/actions` + +--- + +## Task 4: Write Release Notes + +When the user asks to write release notes (MANDATORY for minor/major releases): + +### Step 1: Gather Changes + +```bash +git log vPREVIOUS..vNEW --oneline +``` + +Read the actual code changes (not just commit messages) to understand what was added or fixed. + +### Step 2: Write Release Notes + +**Release title:** Use just `vX.Y.Z` (e.g., `v1.4.1`), NOT "Release vX.Y.Z". + +**Required structure:** + +1. **"What's New"** (1-2 sentences): Brief intro explaining the main change +2. **"New Features" / "Bug Fixes" / "Improvements"**: Grouped bullet points with **bold feature names** and descriptions +3. **"Where to Find It"**: Tell users where they can access the new feature or see the fix +4. **Breaking Changes Warning** (if applicable): See below + +**Style guidelines:** +- Use `### Heading` for sections +- Use **bold** for feature names in bullet points +- Keep descriptions on the same line as the feature name +- Minimal emoji usage (sparingly, not on every line) +- Always end with "Where to Find It" section +- End with: `**Full Changelog**: https://github.com/DanielVolz/medassist-ng/compare/vPREV...vNEW` + +**ONLY include user-relevant changes.** DO NOT include: +- ❌ Technical implementation details (new columns, endpoints, database changes) +- ❌ Number of tests added +- ❌ Internal API changes (unless breaking) +- ❌ Excessive emoji on every bullet point +- ❌ .gitignore changes or other developer-only file changes +- ❌ AI/Copilot instruction updates +- ❌ CI/CD workflow changes (unless affecting users) +- ❌ Code refactoring without user-visible changes + +### Example: Good Release Notes + +```markdown +## What's New + +This release introduces a medication refill tracking feature and improves the mobile user experience. + +### New Features + +- **Medication Refill**: Track when you refill your medications with a single click. Add full packs or individual pills and view complete refill history. +- **Automatic Stock Updates**: Stock levels are automatically recalculated after each refill. +- **Refill History**: Each medication shows a complete history of all refills with timestamps. + +### Mobile Improvements + +- **Centered Tooltips**: Info tooltips now display centered on screen for better readability. +- **Touch-friendly**: Tooltips close automatically when scrolling on touch devices. + +### Where to Find It + +The refill button appears in the medication detail modal and in the edit form for each medication. + +**Full Changelog**: https://github.com/DanielVolz/medassist-ng/compare/v1.2.3...v1.3.0 +``` + +### Breaking Changes Warning + +If the update breaks existing configurations or stored data, it MUST be prominently warned: + +**Breaking Changes include:** +- Database schema changes without automatic migration +- Removed or renamed ENV variables +- Changed API endpoints +- Incompatible `.env` format changes +- Loss of stored data after update + +**Format:** + +```markdown +## ⚠️ BREAKING CHANGES - Please read before updating! + +**Database migration required**: This update changes the database schema. +Existing installations need to: +1. Create backup of `data/` folder +2. Stop containers +3. Perform update +4. If issues occur: Rollback using backup + +**ENV variables changed**: +- `OLD_VAR` was renamed to `NEW_VAR` +- `REMOVED_VAR` is no longer supported +``` + +**What is NOT a Breaking Change:** +- ✅ New optional columns with DEFAULT values +- ✅ New ENV variables (with sensible defaults) +- ✅ New features that don't affect existing data +- ✅ Bug fixes that correct behavior + +### Step 3: Publish + +Present the release notes to the user. They will copy them to the GitHub release page or ask you to publish via: +```bash +gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES_HERE" +``` + +--- + +## Complete Workflow Summary + +``` +Code complete & tests pass locally + ↓ +1. Create feature branch (fix/... or feat/...) +2. Commit, push, create PR +3. Wait for CI (backend-test + frontend-build) +4. Merge PR to main (squash + delete branch) + ↓ +Ready for release? + ↓ +5. Check current version (git tag + package.json) +6. Analyze changes → determine SemVer level +7. Run ./scripts/release.sh + (or manually: branch → version bump → PR → CI → merge → tag) + ↓ +8. Write release notes (mandatory for minor/major) +9. Publish GitHub release + ↓ +Docker images built automatically via CI +``` \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6cbea6e..fa79193 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -180,141 +180,6 @@ gh pr merge --squash --delete-branch | `.github/workflows/test.yml` | Pull Requests | Run tests, block PR on failures | | `.github/workflows/docker-build.yml` | Push to main, Tags | Tests + Build and push Docker images | -### Adding New Code - Checklist -1. ✅ Implement feature -2. ✅ Write tests for the feature -3. ✅ Run `npm run test:coverage` locally -4. ✅ Coverage must not decrease -5. ✅ Create and push feature branch -6. ✅ Create Pull Request -7. ✅ Wait until CI is green -8. ✅ Merge PR (branch is automatically deleted) - -## GitHub Releases - -> ⚠️ **IMPORTANT**: All GitHub Releases must be written in **English**! - -### Release Workflow (MANDATORY for minor/major releases) - -The `main` branch is protected - releases are created via GitHub's release UI or API. - -**Release Process:** -1. Create a new release on GitHub with tag `vX.Y.Z` -2. **Automatic Version Bump**: A GitHub Action (`version-bump.yml`) automatically updates `package.json` versions to match the release tag -3. User asks AI to write release notes: "Write the release notes for vX.Y.Z" -4. AI writes descriptive release notes following the style guide below -5. User publishes the release with the written notes - -> ⚠️ **MANDATORY for minor and major releases**: The AI assistant MUST write proper descriptive release notes! -> Do NOT just publish the auto-generated commit list. Follow the process above. - -**AI Assistant Release Notes Workflow:** -1. When user asks to write release notes for a version: - - Check commits since previous tag: `git log vPREV..vNEW --oneline` - - Read through the changes to understand what was added/fixed - - Write release notes following the style guide below - - Present the notes to the user for copying to GitHub - -### Creating Release Notes - -> ⚠️ **MANDATORY**: GitHub Releases MUST contain a written message! -> Not just auto-generated commit lists, but a brief descriptive text. - -**Release title:** Use just `vX.Y.Z` (e.g., `v1.4.1`), NOT "Release vX.Y.Z". - -**Keep it informative but concise.** Users want to know what changed and where to find it. - -**Required structure of release notes:** - -1. **"What's New"** (1-2 sentences): Brief intro explaining the main change -2. **"New Features" / "Improvements"**: Grouped bullet points with **bold feature names** and descriptions -3. **"Where to Find It"**: Tell users where they can access the new feature -4. **Breaking Changes Warning** (if applicable): See below - -**Style guidelines:** -- Use `### Heading` for sections (New Features, Improvements, Security, etc.) -- Use **bold** for feature names in bullet points -- Keep descriptions on the same line as the feature name -- Minimal emoji usage (sparingly, not on every line) -- Always end with "Where to Find It" section - -**DO NOT include:** -- ❌ Technical implementation details (new columns, endpoints, database changes) -- ❌ Number of tests added -- ❌ Internal API changes (unless breaking) -- ❌ Excessive emoji on every bullet point -- ❌ .gitignore changes or other developer-only file changes -- ❌ AI/Copilot instruction updates -- ❌ CI/CD workflow changes (unless affecting users) -- ❌ Code refactoring without user-visible changes - -**Only include user-relevant changes** - things that affect what users see or experience in the app. - -**Example of good release notes:** - -```markdown -## What's New - -This release introduces a medication refill tracking feature and improves the mobile user experience. - -### New Features - -- **Medication Refill**: Track when you refill your medications with a single click. Add full packs or individual pills and view complete refill history. -- **Automatic Stock Updates**: Stock levels are automatically recalculated after each refill. -- **Refill History**: Each medication shows a complete history of all refills with timestamps. - -### Mobile Improvements - -- **Centered Tooltips**: Info tooltips now display centered on screen for better readability. -- **Touch-friendly**: Tooltips close automatically when scrolling on touch devices. - -### Where to Find It - -The refill button appears in the medication detail modal and in the edit form for each medication. - -**Full Changelog**: https://github.com/DanielVolz/medassist-ng/compare/v1.2.3...v1.3.0 -``` - -### Breaking Changes Warning (CRITICAL!) - -> ⚠️ **MANDATORY**: If an update breaks existing configurations or stored data, it MUST be prominently warned about in the release notes! - -**Breaking Changes include:** -- Database schema changes without automatic migration -- Removed or renamed ENV variables -- Changed API endpoints -- Incompatible `.env` format changes -- Loss of stored data after update - -**Format for Breaking Changes:** - -```markdown -## ⚠️ BREAKING CHANGES - Please read before updating! - -**Database migration required**: This update changes the database schema. -Existing installations need to: -1. Create backup of `data/` folder -2. Stop containers -3. Perform update -4. If issues occur: Rollback using backup - -**ENV variables changed**: -- `OLD_VAR` was renamed to `NEW_VAR` -- `REMOVED_VAR` is no longer supported - -**Medication data**: Intake schedules with only one time entry will be automatically -migrated. Please verify all times are correct after update. -``` - -**What is NOT a Breaking Change:** -- ✅ New optional columns with DEFAULT values -- ✅ New ENV variables (with sensible defaults) -- ✅ New features that don't affect existing data -- ✅ Bug fixes that correct behavior - -**Rule of thumb**: If a user can simply run `docker compose pull && docker compose up -d` -without adjusting anything → Not a Breaking Change. - ## Key Patterns ### Backend Routes (`backend/src/routes/`)