@afoures/auto-release 0.2.12 → 0.3.0

package/docs/recommended-usage.md

@@ -0,0 +1,155 @@
+# Recommended Usage Guide
+
+This guide explains the recommended automated release workflow for the `auto-release` CLI.
+
+## Overview
+
+This release workflow streamlines your release process by combining developer-led change tracking with CI-driven release generation. This approach offers several key benefits:
+
+- **Testing before production**: Release candidates can be tested on staging before final deployment
+- **Automated changelogs**: Change descriptions are automatically compiled into changelog
+- **Safety through PRs**: All releases go through pull request review, preventing accidental deployments
+- **Audit trail**: Every release is traceable through recorded change files and version history
+
+## Workflow Diagram
+
+// TODO
+
+## The Automated Release Workflow
+
+### Step 1: Developer Records Changes
+
+Throughout development, developers record changes as they are made:
+
+```bash
+# Record a feature change for a specific project
+auto-release record-change --project myapp --type feature
+
+# Record a bug fix
+auto-release record-change --project myapp --type fix
+
+# Record a breaking change
+auto-release record-change --project myapp --type breaking
+```
+
+This command:
+
+- Creates a change file in `.changes/<project>/`
+- Opens your default editor for a detailed description
+- Generates a unique filename with timestamp
+
+After recording, commit the change file alongside your code changes:
+
+```bash
+git add .changes/myapp/
+git commit -m "feat: add new login feature"
+git push
+```
+
+### Step 2: Merge to Main Branch
+
+Push your changes to the main branch through your normal process.
+
+Before pushing, you can use (locally or in CI)
+
+```bash
+auto-release check
+```
+
+to validate configuration and change files.
+
+### Step 3: CI Generates Release PR
+
+When changes are pushed to main, CI automatically generates a release PR:
+
+```bash
+auto-release generate-release-pr --filter myapp
+```
+
+This command:
+
+- Scans `.changes/` for unreleased changes
+- Bumps project's version numbers based on change types
+- Generates a changelog from recorded changes
+- Creates a release branch (`release/<project>`)
+- Opens a pull request for review
+
+### Step 4: CI Tests and Deploys to Staging
+
+The release PR can trigger testing and staging deployment:
+
+```bash
+# Run your test suite
+# Build the project
+# Deploy to staging environment
+```
+
+This step ensures the release candidate works correctly before production.
+
+### Step 5: Merge Release PR
+
+After staging tests pass, the team reviews and merges the release PR:
+
+- Review the version changes and changelog
+- Approve and merge to main
+- Version changes now land on main
+
+### Step 6: CI Tags and Deploys to Production
+
+When the release PR is merged, CI creates tags and triggers production deployment:
+
+```bash
+auto-release tag-release-commit
+```
+
+This command:
+
+- Compares HEAD with HEAD^1 to find the merge commit
+- Creates git tags for each project (`<project>@<version>`)
+- Creates releases on the platform (GitHub/GitLab)
+- Tags trigger production deployment CI
+
+## Hot Fixes and Manual Releases
+
+The `manual-release` command is available for special scenarios:
+
+```bash
+auto-release manual-release --project myapp
+```
+
+**Usecases:**
+
+- Local testing of release workflows
+- Emergency hot fixes requiring immediate release
+- Initial release setup
+
+**Important warnings:**
+
+- Not intended for CI use
+- Bypasses the automated workflow safety checks
+- Use only when the automated workflow is not suitable
+
+## Best Practices for Developers
+
+### When to Record Changes
+
+Record changes as soon as you complete a feature or fix. Don't wait until release time, this ensures accurate changelogs and better documentation.
+
+### Writing Effective Change Descriptions
+
+Keep descriptions clear and concise:
+
+- Explain what changed and why
+- Include relevant context for end users
+- Mention breaking changes prominently
+- Include migration strategies if needed
+
+### Reviewing Release PRs
+
+When reviewing release PRs:
+
+- Verify the version bump is correct given your versioning strategy
+- Read the generated changelog for clarity
+- Ensure all expected changes are included
+
+If changes are needed, you should not modify the release PR but submit code through your normal process.

package/package.json

@@ -1,18 +1,30 @@
 {
   "name": "@afoures/auto-release",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "description": "A file based release management tool for monorepos",
   "homepage": "https://github.com/afoures/auto-release#readme",
   "bugs": {
     "url": "https://github.com/afoures/auto-release/issues"
   },
+  "author": "Antoine Fourès <contact@afoures.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afoures/auto-release.git"
   },
-  "author": "Antoine Fourès <contact@afoures.com>",
+  "license": "MIT",
+  "bin": {
+    "auto-release": "./dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "package.json",
+    "README.md"
+  ],
   "type": "module",
   "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -32,16 +44,6 @@
       "import": "./dist/versioning.mjs"
     }
   },
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
-  "bin": {
-    "auto-release": "./dist/bin.mjs"
-  },
-  "files": [
-    "dist",
-    "package.json",
-    "README.md"
-  ],
   "dependencies": {
     "@clack/prompts": "1.0.0-alpha.9",
     "arkregex": "^0.0.5",
@@ -54,17 +56,16 @@
   "devDependencies": {
     "@types/mdast": "^4.0.4",
     "@types/node": "^24.10.4",
-    "bumpp": "^10.3.2",
     "oxfmt": "^0.20.0",
     "oxlint": "^1.35.0",
     "tsdown": "^0.18.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
   },
-  "packageManager": "pnpm@8.15.9+sha512.499434c9d8fdd1a2794ebf4552b3b25c0a633abcee5bb15e7b5de90f32f47b513aca98cd5cfd001c31f0db454bc3804edccd578501e4ca293a6816166bbd9f81",
   "engines": {
     "node": ">=22.0.0"
   },
+  "packageManager": "pnpm@8.15.9+sha512.499434c9d8fdd1a2794ebf4552b3b25c0a633abcee5bb15e7b5de90f32f47b513aca98cd5cfd001c31f0db454bc3804edccd578501e4ca293a6816166bbd9f81",
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",