@afoures/auto-release 0.2.12 → 0.4.0

package/docs/configuration.md

@@ -0,0 +1,195 @@
+# Configuration
+
+## Projects
+
+The `projects` object defines each releasable unit:
+
+```typescript
+projects: {
+  'my-app': {
+    // Components: where versions are read/written
+    components: [
+      node('packages/my-app'),
+      node('packages/shared'),
+    ],
+
+    // Versioning strategy
+    versioning: semver(),
+
+    // Changelog file path
+    changelog: 'apps/my-app/CHANGELOG.md',
+  },
+}
+```
+
+## Grouping Projects
+
+Projects can be grouped to release together in a single pull/merge request using the `release_group` option.
+
+### Default Behavior
+
+By default, each project is its own group (releases individually). The group name defaults to the project name.
+
+### Custom Groups
+
+```typescript
+export default define_config({
+  projects: {
+    "web-app": {
+      release_group: "frontend",  // Groups with other "frontend" projects
+      components: [...],
+      versioning: semver(),
+      changelog: "./CHANGELOG.md",
+    },
+    "mobile-app": {
+      release_group: "frontend",  // Same group - released together
+      components: [...],
+      versioning: semver(),
+      changelog: "./CHANGELOG.md",
+    },
+    "api": {
+      // No release_group - defaults to "api" (individual release)
+      components: [...],
+      versioning: semver(),
+      changelog: "./CHANGELOG.md",
+    },
+  },
+});
+```
+
+**Resulting behavior:**
+
+- Changes to `web-app` or `mobile-app` create a single PR with both projects
+- Changes to `api` create an individual PR
+- Branch name: `release/frontend` for grouped, `release/api` for individual
+- PR title: `release: web-app@1.2.0, mobile-app@2.0.0` for grouped
+
+### Default Project Config
+
+Set default options for all projects:
+
+```typescript
+export default define_config({
+  default_project_config: {
+    release_group: "shared",  // All projects default to this group
+    options: {
+      skip_release_if_no_change_file: true,
+    },
+  },
+  projects: { ... },
+});
+```
+
+### Options
+
+#### `skip_release_if_no_change_file`
+
+When `true`, skip creating a release PR for projects without change files.
+
+```typescript
+projects: {
+  "my-app": {
+    components: [...],
+    versioning: semver(),
+    changelog: "CHANGELOG.md",
+    options: {
+      skip_release_if_no_change_file: true,
+    },
+  },
+}
+```
+
+Useful for grouped projects where some projects may not have changes in every release cycle.
+
+## Versioning Strategies
+
+```typescript
+import { semver, calver, markver } from 'auto-release/versioning'
+
+// Semantic versioning: 1.2.3
+versioning: semver()  // Change types: major, minor, patch
+
+// Calendar versioning: 2025.1.2
+versioning: calver()  // Change types: feature, fix
+
+// Marketing versioning: 1.0.0
+versioning: markver()  // Change types: marketing, feature, fix
+```
+
+## Git Platforms
+
+### GitHub
+
+```typescript
+import { github } from 'auto-release/providers'
+
+git: {
+  platform: github({
+    token: process.env.GITHUB_TOKEN!,
+    owner: 'your-org',
+    repo: 'your-repo',
+  }),
+  target_branch: 'main',
+  tag_generator: ({ project, version }) => `${project.name}-${version}`,
+}
+```
+
+### GitLab
+
+```typescript
+import { gitlab } from 'auto-release/providers'
+
+git: {
+  platform: gitlab({
+    token: process.env.GITLAB_TOKEN!,
+    project_id: 'your-project-id',
+  }),
+  target_branch: 'main',
+}
+```
+
+## Tag Generator
+
+Customize the format of git tags created during release:
+
+```typescript
+git: {
+  // ... other options
+  tag_generator: ({ project, version }) => `${project.name}-${version}`,
+}
+```
+
+**Default**: `project-name@version` (e.g., `my-app@1.2.3`)
+
+**Custom examples**:
+
+```typescript
+// Version only: 1.2.3
+tag_generator: ({ version }) => `${version}`
+
+// Prefixed: v1.2.3
+tag_generator: ({ version }) => `v${version}`
+
+// With prefix: release/my-app-1.2.3
+tag_generator: ({ project, version }) => `release/${project.name}-${version}`
+```
+
+## Components
+
+Components define version sources:
+
+- **`node(path)`**: any node project with package.json
+- **`bun(path)`**: any bun project with package.json
+- **`expo(path)`**: any Expo project with package.json and app.json
+- **`php(path)`**: any PHP project with composer.json
+
+```typescript
+import { node, expo, php } from 'auto-release/components'
+
+components: [
+  node('packages/web'),
+  bun('packages/bff'),
+  expo('apps/mobile'),
+  php('packages/api'),
+]
+```

package/docs/lexicon.md

@@ -0,0 +1,23 @@
+# `auto-release` Lexicon
+
+This is a list of words and phrases used in `auto-release` to help contributors and users have a shared understanding of various concepts in the project.
+
+- **change file** - A markdown file documenting a single change to a project. Change files are stored in the changes directory with the format `<kind>.<slug>.md` (e.g., `major.add-authentication.md`). Change files are stackable, running `generate-release-pr` will apply any number of change files correctly to calculate the next version and generate changelog entries.
+- **changes directory** - The `.changes/` folder where change files are stored. This directory contains subdirectories for each project (e.g., `.changes/my-app/`), and each subdirectory contains the change files for that project.
+- **change kind** - The type of change represented by a change file (e.g., `major`, `minor`, `patch`, `feature`, `fix`). The valid kinds for a project are defined by its versioning strategy's `allowed_changes`. This determines how the version will be bumped.
+- **slug** - A unique identifier for a change file, used in the filename between the kind and the `.md` extension. Generated automatically or provided by the user (e.g., `add-authentication` in `major.add-authentication.md`).
+- **project** - A releasable unit in your repository or monorepo. Each project has its own independent versioning strategy, one or more components, its own changelog, and a dedicated subdirectory in the changes directory. Projects are defined in the configuration file.
+- **component** - A source of version information within a project. Components define where versions are read from and written to. Built-in component types include `node()/bun()` for package.json files, `expo()` for app.json files, and `php()` for composer.json files. All components within a project must have the same version.
+- **versioning strategy** - Defines how versions are calculated and formatted for a project. Each strategy specifies valid change kinds and a `bump()` function to compute the next version from the current version and collected change kinds.
+- **bump**
+  - (1) The command/process to apply all current change files, calculate new versions, update all component files, update changelogs, and remove processed change files.
+  - (2) The act of updating a project's version to a new version based on change files.
+- **changelog** - A markdown file where release entries are appended for a project. Each project specifies its changelog path in the configuration. Changelog entries are generated from change file summaries using the formatter.
+- **formatter** - Controls how changelogs and release notes are generated from change files. The formatter can parse markdown from change files and format changelog sections. The default formatter groups changes by kind and outputs markdown lists.
+- **target branch** - The main branch where releases are merged to (typically `main` or `master`). This is the branch that release PRs target and where version tags are created.
+- **release branch** - A branch created by the `generate-release-pr` command containing updated versions in all component files, new changelog entries, and removed change files. Format: `<prefix>/<project-name>` (e.g., `release/my-app`).
+- **release PR** - A pull request from a release branch to the target branch, containing all version updates and changelog changes for a release. Created or updated by the `generate-release-pr` command.
+- **git platform** - The hosting service for your git repository (GitHub or GitLab). The git platform integration is used to create and update release PRs, manage release notes, and interact with the repository API. Configured in the configuration file with authentication tokens.
+- **tag** - A git tag created when a version change is detected on the target branch after a release PR is merged. Format: `<project-name>@<version>` (e.g., `my-app@1.2.3`). Created by the `tag-release-commit` command, typically run in CI.
+- **release** - The combination of versioning, updating changelogs, creating a git tag, and publishing release notes on the git platform. This happens when a release PR is merged and the `tag-release-commit` command detects the version change.
+- **config file** - The `auto-release.config.ts` TypeScript configuration file at the root of your repository. Defines projects, their components, versioning strategies, changelog paths, and git platform settings.

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,31 @@
 {
   "name": "@afoures/auto-release",
-  "version": "0.2.12",
+  "version": "0.4.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"
   },
+  "license": "MIT",
+  "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>",
+  "bin": {
+    "auto-release": "./dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [],
   "type": "module",
   "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -32,16 +45,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,23 +57,23 @@
   "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",
     "test": "vitest",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint",
-    "format": "oxfmt"
+    "format": "oxfmt",
+    "auto-release.local": "node ./dist/bin.mjs"
   }
 }