package-versioner 0.7.0 → 0.7.2

package/README.md

@@ -5,7 +5,7 @@
   <img src="https://img.shields.io/npm/v/package-versioner" /></a>
 <a href="https://www.npmjs.com/package/package-versioner" alt="NPM Downloads">
   <img src="https://img.shields.io/npm/dw/package-versioner" /></a>
-
+<br/><br/>
 A lightweight yet powerful CLI tool for automated semantic versioning based on Git history and conventional commits. Supports both single package projects and monorepos with flexible versioning strategies.
 
 ## Features
@@ -92,25 +92,24 @@ For detailed examples of how to use this in CI/CD pipelines, see [CI/CD Integrat
 
 ## Configuration
 
-Customize behavior by creating a `version.config.json` file in your project root:
+Customize behaviour by creating a `version.config.json` file in your project root:
 
 ```json
 {
   "preset": "angular",
   "versionPrefix": "v",
-  "tagTemplate": "${prefix}${version}",
-  "packageTagTemplate": "${packageName}@${prefix}${version}",
+  "tagTemplate": "${packageName}@${prefix}${version}",
+  "packageSpecificTags": true,
   "commitMessage": "chore: release ${packageName}@${version} [skip ci]",
   "updateChangelog": true,
   "changelogFormat": "keep-a-changelog",
-  "monorepo": {
-    "synced": true,
-    "skip": [
-      "docs",
-      "e2e"
-    ],
-    "packagePath": "packages"
-  },
+  "synced": true,
+  "skip": [
+    "docs",
+    "e2e"
+  ],
+  "packages": ["@mycompany/*"],
+  "mainPackage": "primary-package",
   "cargo": {
     "enabled": true,
     "paths": ["src/", "crates/"]
@@ -118,15 +117,107 @@ Customize behavior by creating a `version.config.json` file in your project root
 }
 ```
 
-**Notes:** 
-- Options like `synced`, `packages`, and `updateInternalDependencies` enable monorepo-specific behaviours.
-- The `tagTemplate` and `packageTagTemplate` allow you to customize how Git tags are formatted for releases.
-- The `commitMessage` template can include CI skip tokens like `[skip ci]` if you want to prevent CI runs after version commits (e.g., `"commitMessage": "chore: release ${packageName}@${version} [skip ci]"`). See [CI/CD Integration](./docs/CI_CD_INTEGRATION.md) for more details.
-- The `updateChangelog` option controls whether to automatically generate and update changelogs for each package (default: true).
-- The `changelogFormat` option sets the changelog style to either "keep-a-changelog" (default) or "angular".
-- The `cargo` options can help when working with Rust projects:
-  - `enabled` (default: `true`): Set to `false` to disable Cargo.toml version handling
-  - `paths` (optional): Specify directories to search for Cargo.toml files
+### Configuration Options
+
+#### General Options (All Projects)
+- `preset`: Conventional commits preset to use for version calculation (default: "angular")
+- `versionPrefix`: Prefix for version numbers in tags (default: "v")
+- `tagTemplate`: Template for Git tags (default: "${prefix}${version}")
+- `commitMessage`: Template for commit messages (default: "chore(release): ${version}")
+- `updateChangelog`: Whether to automatically update changelogs (default: true)
+- `changelogFormat`: Format for changelogs - "keep-a-changelog" or "angular" (default: "keep-a-changelog")
+- `cargo`: Options for Rust projects:
+  - `enabled`: Whether to handle Cargo.toml files (default: true)
+  - `paths`: Directories to search for Cargo.toml files (optional)
+
+#### Monorepo-Specific Options
+- `synced`: Whether all packages should be versioned together (default: true)
+- `skip`: Array of package names to exclude from versioning
+- `packages`: Array of package names or patterns to target for versioning. Supports exact names, scope wildcards, and global wildcards (e.g., ["@scope/package-a", "@scope/*", "*"])
+- `mainPackage`: Package name whose commit history should drive version determination
+- `packageSpecificTags`: Whether to enable package-specific tagging behaviour (default: false)
+- `updateInternalDependencies`: How to update internal dependencies ("patch", "minor", "major", or "inherit")
+
+For more details on CI/CD integration and advanced usage, see [CI/CD Integration](./docs/CI_CD_INTEGRATION.md).
+
+### Package Targeting
+
+The `packages` configuration option allows you to specify which packages should be processed for versioning. It supports several pattern types:
+
+#### Exact Package Names
+```json
+{
+  "packages": ["@mycompany/core", "@mycompany/utils", "standalone-package"]
+}
+```
+
+#### Scope Wildcards
+Target all packages within a specific scope:
+```json
+{
+  "packages": ["@mycompany/*"]
+}
+```
+
+#### Global Wildcard
+Target all packages in the workspace:
+```json
+{
+  "packages": ["*"]
+}
+```
+
+#### Mixed Patterns
+Combine different pattern types:
+```json
+{
+  "packages": ["@mycompany/*", "@utils/logger", "legacy-package"]
+}
+```
+
+**Note**: Package discovery is handled by your workspace configuration (pnpm-workspace.yaml, package.json workspaces, etc.). The `packages` option only filters which discovered packages to process.
+
+### Package-Specific Tagging
+
+The `packageSpecificTags` option controls whether the tool creates and searches for package-specific Git tags:
+
+- **When `false` (default)**: Creates global tags like `v1.2.3` and searches for the latest global tag
+- **When `true`**: Creates package-specific tags like `@scope/package-a@v1.2.3` and searches for package-specific tags
+
+This option works in conjunction with `tagTemplate` to control tag formatting. The `tagTemplate` is used for all tag creation, with the `packageSpecificTags` boolean controlling whether the `${packageName}` variable is populated:
+
+- When `packageSpecificTags` is `false`: The `${packageName}` variable is empty, so templates should use `${prefix}${version}`
+- When `packageSpecificTags` is `true`: The `${packageName}` variable contains the package name
+
+**Examples:**
+
+For single-package repositories or synced monorepos:
+```json
+{
+  "packageSpecificTags": true,
+  "tagTemplate": "${packageName}@${prefix}${version}"
+}
+```
+Creates tags like `my-package@v1.2.3`
+
+For global versioning:
+```json
+{
+  "packageSpecificTags": false,
+  "tagTemplate": "${prefix}${version}"
+}
+```
+Creates tags like `v1.2.3`
+
+**Important Notes:**
+- In **synced mode** with a single package, `packageSpecificTags: true` will use the package name even though all packages are versioned together
+- In **synced mode** with multiple packages, package names are not used regardless of the setting
+- In **async mode**, each package gets its own tag when `packageSpecificTags` is enabled
+
+With package-specific tagging enabled, the tool will:
+1. Look for existing tags matching the configured pattern for each package
+2. Create new tags using the same pattern when releasing
+3. Fall back to global tag lookup if no package-specific tags are found
 
 ## How Versioning Works