### Install, Build, and Test Library

Source: https://github.com/jscutlery/semver/blob/main/CONTRIBUTING.md

Commands to install dependencies, build the library, and run tests. Ensure the library is built before running e2e tests.

```sh
pnpm install

pnpm build

pnpm test
```

--------------------------------

### Install for Specific Projects

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Limits the installation of version targets to a comma-separated list of projects.

```bash
nx g @jscutlery/semver:install \
  --syncVersions=false \
  --baseBranch=main \
  --projects=lib-a,lib-b \
  --preset=conventionalcommits
```

--------------------------------

### Install @jscutlery/semver

Source: https://github.com/jscutlery/semver/blob/main/README.md

Commands to install the package and initialize the plugin in an Nx workspace.

```sh
npm install -D @jscutlery/semver
nx g @jscutlery/semver:install
```

--------------------------------

### Example Workspace Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

The resulting workspace-level version target configuration.

```json
{
  "projects": {
    "workspace": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "syncVersions": true,
            "baseBranch": "main",
            "tagPrefix": "v",
            "preset": "angular"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Example Project Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

The resulting version target configuration added to project.json.

```json
{
  "targets": {
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "postTargets": [],
        "baseBranch": "main",
        "preset": "conventionalcommits"
      }
    }
  }
}
```

--------------------------------

### Install in Independent Mode

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Configures version targets for each publishable project individually.

```bash
nx g @jscutlery/semver:install --syncVersions=false --baseBranch=main --preset=conventionalcommits
```

--------------------------------

### install(options: SchemaOptions)

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

The install generator function configures the semver plugin in an Nx workspace by updating project files and setting up versioning and changelog scripts.

```APIDOC
## install(options: SchemaOptions)

### Description
Automatically configures @jscutlery/semver in your Nx workspace by creating or updating project.json files, setting up changelog generation, and configuring versioning modes.

### Parameters
- **syncVersions** (boolean) - Required - Version all projects together (true) or independently (false).
- **baseBranch** (string) - Required - Git branch to push to (e.g., 'main', 'master').
- **projects** (string[]) - Optional - Specific projects to configure; if omitted, all publishable projects are configured.
- **enforceConventionalCommits** (boolean) - Required - Validate commits follow conventional commit format.
- **skipInstall** (boolean) - Required - Skip npm install after configuration.
- **commitMessageFormat** (string) - Optional - Custom commit message template.
- **preset** (Preset) - Required - Changelog preset (e.g., conventionalcommits, angular).
```

--------------------------------

### Configure Basic GitLab Release

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/gitlab-executor.md

Example configuration for setting up a basic GitLab release within nx.json or project.json.

```json
// In nx.json or project.json
{
  "gitlab": {
    "executor": "@jscutlery/semver:gitlab",
    "options": {
      "tag": "{tag}",
      "name": "Release {version}",
      "description": "{notes}"
    }
  }
}

// In version target post-targets:
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "postTargets": ["gitlab"]
    }
  }
}
```

--------------------------------

### Configure Release Assets

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/gitlab-executor.md

Examples of defining single and multiple assets for a release.

```typescript
// Single asset
{
  "name": "release-binary",
  "url": "https://example.com/releases/v1.0.0/my-app-1.0.0-x64.exe"
}

// Multiple assets
const assets = [
  { "name": "tarball", "url": "https://example.com/v1.0.0.tar.gz" },
  { "name": "zip", "url": "https://example.com/v1.0.0.zip" },
  { "name": "changelog", "url": "https://example.com/CHANGELOG.md" }
];
```

--------------------------------

### Version Calculation Scenarios

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/version-calculation.md

Examples demonstrating how different commit histories and options result in specific version bumps.

```text
Last version: 1.2.3
Commits: feat(parser): add new syntax
Result: 1.3.0 (minor bump)
```

```text
Last version: 1.2.3
Commits:
  - fix(parser): bug X
  - fix(lexer): bug Y
  - feat(api): new endpoint
Result: 1.3.0 (minor from feature)
```

```text
Last version: 1.2.3
Commits:
  BREAKING CHANGE: API deprecated
  Removed old endpoint
Result: 2.0.0 (major bump)
```

```text
Last version: 1.2.3
Commits: none relevant
Options: allowEmptyRelease = true
Result: 1.2.4 (patch bump anyway)
```

```text
Last version: 1.0.0-alpha.0
Commits: (none, but releaseAs=prerelease)
Result: 1.0.0-alpha.1 (next prerelease)
```

--------------------------------

### Perform initial prerelease versioning

Source: https://github.com/jscutlery/semver/blob/main/README.md

Example command to trigger a prerelease version bump based on commit history.

```bash
nx version my-project --releaseAs=prerelease --preid=alpha
```

--------------------------------

### Changelog Markdown Format Example

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/version-calculation.md

Illustrates the expected structure of the generated CHANGELOG.md file.

```markdown
# Changelog

This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).

## [1.1.0] (2024-01-15)

### Features

- New API endpoint ([a1b2c3d](https://github.com/org/repo/commit/a1b2c3d))
- Improved parser ([d4e5f6g](https://github.com/org/repo/commit/d4e5f6g))

### Bug Fixes

- Fixed crash in error handler ([h7i8j9k](https://github.com/org/repo/commit/h7i8j9k))

## [1.0.0] (2024-01-01)

... (previous versions)
```

--------------------------------

### Install with Custom Commit Message

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Configures a custom format for the release commit message.

```bash
nx g @jscutlery/semver:install \
  --syncVersions=false \
  --baseBranch=main \
  --commitMessageFormat="release: {projectName} {version}" \
  --preset=conventionalcommits
```

--------------------------------

### Configure synced versioning with post-targets

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/version-executor.md

Example configuration for synchronized versioning across projects with post-execution targets and custom tag prefixes.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "syncVersions": true,
      "push": true,
      "postTargets": ["build", "github"],
      "tagPrefix": "v"
    }
  }
}
```

--------------------------------

### Use Template Variables in Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/gitlab-executor.md

Example configuration utilizing template variables for dynamic release metadata.

```json
{
  "gitlab": {
    "executor": "@jscutlery/semver:gitlab",
    "options": {
      "tag": "{tag}",
      "name": "{projectName} {version}",
      "description": "{notes}",
      "releasedAt": "2024-01-15T10:30:00Z",
      "milestones": ["v{version}"]
    }
  }
}
```

--------------------------------

### Basic GitHub Release Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/github-executor.md

Example configuration for a basic release using the GitHub executor within an Nx project.

```json
// In nx.json project.json
{
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "notes": "{notes}"
    }
  }
}

// Then in version target:
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "postTargets": ["github"]
    }
  }
}
```

--------------------------------

### Configure basic version bump

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/version-executor.md

Example configuration for enabling versioning with automatic push to the main branch.

```json
// In nx.json or project.json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "push": true,
      "baseBranch": "main"
    }
  }
}

// Execute with:
// nx run my-project:version
```

--------------------------------

### Configure GitLab Release with Assets and Milestones

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/gitlab-executor.md

Example configuration including additional release metadata such as assets and milestones.

```json
{
  "gitlab": {
    "executor": "@jscutlery/semver:gitlab",
    "options": {
      "tag": "{tag}",
      "name": "{projectName} {version}",
      "description": "{notes}",
      "milestones": ["v{version}"],
      "assets": [
        {
          "name": "tarball",
          "url": "https://example.com/releases/v{version}.tar.gz"
        },
        {
          "name": "zip",
          "url": "https://example.com/releases/v{version}.zip"
        }
      ]
    }
  }
}
```

--------------------------------

### Install in Synced Mode

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Configures a workspace-level version target for synchronized versioning across projects.

```bash
nx g @jscutlery/semver:install --syncVersions=true --baseBranch=main --preset=angular
```

--------------------------------

### SchemaOptions Interface Definition

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Defines the configuration options required for the installation generator.

```typescript
export interface SchemaOptions {
  syncVersions: boolean;
  baseBranch: string;
  projects?: string[];
  enforceConventionalCommits: boolean;
  skipInstall: boolean;
  commitMessageFormat?: string;
  preset: Preset;
}
```

--------------------------------

### Enable npm authentication verification

Source: https://github.com/jscutlery/semver/blob/main/README.md

Configures the version executor to perform a dry-run publish to verify npm credentials before starting the release process.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "verifyNpmAuth": true,
      "push": true
    }
  }
}
```

--------------------------------

### Run GitHub Release Manually

Source: https://github.com/jscutlery/semver/blob/main/packages/semver/src/executors/github/README.md

Execute the github executor directly from the command line to publish a release for a specific tag. Ensure the GitHub CLI is installed.

```bash
nx run my-project:github --tag v1.0.0 [...options]
```

--------------------------------

### Install Skipping npm Install

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Prevents the generator from automatically running npm install after configuration.

```bash
nx g @jscutlery/semver:install \
  --syncVersions=false \
  --baseBranch=main \
  --skipInstall=true \
  --preset=conventionalcommits
```

--------------------------------

### Execute Release Commands

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/README.md

Run versioning commands to preview changes, create a new version, or push to a remote repository.

```bash
# Preview changes
nx run lib:version --dryRun

# Create version
nx run lib:version

# With push to remote
nx run lib:version --push
```

--------------------------------

### Skip release for specific commit types

Source: https://github.com/jscutlery/semver/blob/main/README.md

Examples of commit messages that may be ignored when using the --skipCommitTypes option.

```text
docs(project): update documentation about new feature
```

```text
docs(project): update documentation about new feature
fix(project): get rig of annoying bug
```

--------------------------------

### Execute Release Commands

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/README.md

Commands used to preview and execute versioning and changelog generation via Nx.

```bash
nx run project:version --dryRun
```

```bash
nx run project:version --push
```

--------------------------------

### Advanced Release with Assets and Auto-generated Notes

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/github-executor.md

Configuration for creating a release that includes specific file assets and automatically generated release notes.

```json
{
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "title": "Release {version}",
      "generateNotes": true,
      "notesStartTag": "{previousTag}",
      "files": ["dist/**/*.tar.gz", "dist/**/*.zip"]
    }
  }
}
```

--------------------------------

### Configure Prerelease Workflow

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/README.md

Sets up a prerelease versioning strategy using a beta identifier.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "releaseAs": "prerelease",
      "preid": "beta",
      "push": true
    }
  }
}
```

--------------------------------

### Configure Alpha/Beta Prerelease Workflow

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Sets up a prerelease channel using the 'alpha' identifier.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "releaseAs": "prerelease",
      "preid": "alpha"
    }
  }
}
```

```text
1.0.0-alpha.0
1.0.0-alpha.1
1.0.0-alpha.2
```

```bash
nx run lib:version --releaseAs=minor
# Results in 1.1.0
```

--------------------------------

### Execute Versioning Tasks

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/README.md

Common CLI commands for versioning projects, previewing changes, and handling specific release scenarios.

```bash
nx run my-lib:version
```

```bash
nx run my-lib:version --dryRun
```

```bash
nx run my-lib:version --releaseAs=major
```

```bash
nx affected --base=last-release --target=version --parallel=1
```

```bash
nx run workspace:version --dryRun --push
```

```bash
nx run lib:version --releaseAs=prerelease --preid=alpha
```

--------------------------------

### Troubleshoot Git and NPM

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/README.md

Manual verification commands for diagnosing git push and npm publish failures.

```bash
git push origin main
```

```bash
npm publish --dry-run
```

--------------------------------

### Execute Single Package Release

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Commands to preview or perform the versioning and release process.

```bash
# Dry-run to preview
nx run my-lib:version --dryRun

# Execute release
nx run my-lib:version --push
```

--------------------------------

### Using Template Variables in Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/github-executor.md

Demonstrates how to inject dynamic values like tags, project names, and release notes into the executor configuration.

```json
{
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "title": "{projectName} v{version}",
      "notes": "{notes}",
      "notesStartTag": "{previousTag}"
    }
  }
}
```

--------------------------------

### tryBump(options)

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/version-calculation.md

Calculates the recommended new version based on conventional commits, configuration, and dependency tracking.

```APIDOC
## tryBump(options)

### Description
Parses commits to determine if a version bump is required, applying release type overrides and dependency considerations.

### Parameters
- **commitParserOptions** (CommitParserOptions) - Optional - Custom commit parser config
- **preset** (PresetOpt) - Required - Changelog preset
- **projectRoot** (string) - Required - Project directory path
- **tagPrefix** (string) - Required - Git tag prefix filter
- **dependencyRoots** (DependencyRoot[]) - Optional - Dependencies to track
- **releaseType** (ReleaseIdentifier) - Optional - Force specific version increment
- **preid** (string) - Optional - Prerelease identifier
- **versionTagPrefix** (string) - Optional - Original tag prefix
- **syncVersions** (boolean) - Required - Whether in sync mode
- **allowEmptyRelease** (boolean) - Required - Force patch bump even with no changes
- **skipCommitTypes** (string[]) - Required - Commit types to ignore
- **projectName** (string) - Required - Project name for logging
- **workspace** (ProjectsConfigurations) - Optional - Nx workspace config

### Response
- **NewVersion** (object) - Returns a NewVersion object if a bump is required, or null if no changes occurred.
```

--------------------------------

### Run versioning sequentially

Source: https://github.com/jscutlery/semver/blob/main/README.md

Commands and configuration to prevent git lock conflicts when versioning multiple projects.

```bash
nx run-many --target=version --all --parallel=1
nx affected --target=version --parallel=1
```

```json
{
  "targetDefaults": {
    "version": {
      "parallelism": false
    }
  }
}
```

--------------------------------

### Specify release level with --releaseAs

Source: https://github.com/jscutlery/semver/blob/main/README.md

Use these commands to increment the project version by a specific semantic level.

```bash
nx run workspace:version --releaseAs=major
nx run workspace:version --releaseAs=minor
nx run workspace:version --releaseAs=patch
nx run workspace:version --releaseAs=prerelease --preid=alpha
nx run workspace:version --releaseAs=prerelease --preid=beta
```

--------------------------------

### Configure GitHub Actions for semver

Source: https://github.com/jscutlery/semver/blob/main/README.md

Use this workflow to automate versioning and tagging in GitHub Actions. Requires a GITHUB_TOKEN for authentication.

```yaml
name: release

on:
  - workflow_dispatch

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Setup Git
        run: |
          git config user.name "GitHub Bot"
          git config user.email "gituser@example.com"
      - run: pnpm install --frozen-lockfile
      - name: Version
        shell: bash
        run: pnpm nx affected --base=last-release --target=version --parallel=1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Tag last-release
        shell: bash
        run: |
          git tag -f last-release
          git push origin last-release --force
```

--------------------------------

### Configure dependency tracking in nx.json

Source: https://github.com/jscutlery/semver/blob/main/README.md

Sets up target dependencies to ensure versioning cascades correctly through the dependency graph.

```json
{
  "targetDefaults": {
    "version": {
      "dependsOn": ["^version"]
    }
  }
}
```

--------------------------------

### exec(cmd: string, args?: string[]): Promise<string>

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/utilities.md

Executes a system command using Node's execFile API and returns the stdout output.

```APIDOC
## exec(cmd: string, args?: string[])

### Description
Executes a command using Node's execFile API. Handles process cleanup and signal listeners, returning the stdout output as a string.

### Parameters
- **cmd** (string) - Required - Command to execute (e.g., 'git', 'npm')
- **args** (string[]) - Optional - Command arguments

### Returns
- **Promise<string>** - Resolves to stdout output. Rejects with Error containing stderr if command exits with non-zero status.

### Example
```typescript
const output = await exec("git", ["--version"]);
console.log(output);
```
```

--------------------------------

### Version Workspace in Synced Mode

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Command to version the entire workspace when configured in synced mode.

```bash
nx run workspace:version --push
```

--------------------------------

### Configure Unified Product Versioning

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Defines the versioning executor and GitHub release target in project.json for synchronized package releases.

```json
{
  "projects": {
    "workspace": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "syncVersions": true,
            "push": true,
            "baseBranch": "main",
            "tagPrefix": "v",
            "postTargets": ["github"]
          }
        },
        "github": {
          "executor": "@jscutlery/semver:github",
          "options": {
            "tag": "{tag}",
            "title": "v{version}",
            "notes": "{notes}",
            "generateNotes": true,
            "notesStartTag": "{previousTag}"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Configure Monorepo with Multiple Independent Packages

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Sets up versioning and GitHub release targets for multiple independent packages within a monorepo.

```json
{
  "targetDefaults": {
    "version": {
      "parallelism": false
    }
  },
  "projects": {
    "lib-a": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "push": true,
            "baseBranch": "main",
            "postTargets": ["build", "github"],
            "changelogHeader": "# @myorg/lib-a Changelog"
          }
        },
        "github": {
          "executor": "@jscutlery/semver:github",
          "options": {
            "tag": "{tag}",
            "title": "@myorg/lib-a {version}",
            "notes": "{notes}"
          }
        }
      }
    },
    "lib-b": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "push": true,
            "baseBranch": "main",
            "postTargets": ["build", "github"],
            "changelogHeader": "# @myorg/lib-b Changelog"
          }
        },
        "github": {
          "executor": "@jscutlery/semver:github",
          "options": {
            "tag": "{tag}",
            "title": "@myorg/lib-b {version}",
            "notes": "{notes}"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Configure Prerelease with preid

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/errors.md

Use these JSON configurations to correctly associate a preid with a prerelease or premajor release type.

```json
{
  "options": {
    "releaseAs": "prerelease",
    "preid": "alpha"
  }
}
```

```json
{
  "options": {
    "releaseAs": "premajor",
    "preid": "beta"
  }
}
```

--------------------------------

### GitLab release-cli command not found error

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/errors.md

Indicates the release-cli tool is missing from the environment PATH or the CI image.

```text
release-cli: command not found
```

--------------------------------

### Configure GitLab CI for semver

Source: https://github.com/jscutlery/semver/blob/main/README.md

Use this configuration to automate versioning in GitLab CI. Ensure a deploy key is configured to allow pushing tags back to the repository.

```yaml
stages:
  - release

release:
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
      when: manual
  stage: release
  image: node:20.19.3
  before_script:
    - git config --global user.name "GitLab Bot"
    - git config --global user.email "gituser@example.com"
    - git remote set-url origin http://gitlab-ci-token:${DEPLOY_KEY}@gitlab.com/org/project.git
  script:
    - pnpm install --frozen-lockfile
    - pnpm nx affected --target=version --base=last-release --parallel=1
    - git tag -f last-release
    - git push origin last-release --force -o ci.skip
```

--------------------------------

### Configure post-version targets

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

Specify additional Nx targets to run after a version bump, such as building, publishing, or creating a GitHub release.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "push": true,
      "postTargets": ["build", "publish", "github"]
    }
  },
  "build": {
    "executor": "@nx/js:tsc"
  },
  "publish": {
    "executor": "ngx-deploy-npm:deploy",
    "options": {
      "access": "public"
    }
  },
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "notes": "{notes}"
    }
  }
}
```

--------------------------------

### Multi-Service Release Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Configure postTargets to trigger downstream executors like slack notifications or documentation deployments after a version release.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "push": true,
      "postTargets": ["build", "publish", "github", "slack", "docs"]
    }
  },
  "slack": {
    "executor": "custom:slack-notify",
    "options": {
      "channel": "#releases",
      "message": "{projectName} {version} released: {notes}"
    }
  },
  "docs": {
    "executor": "custom:deploy-docs",
    "options": {
      "version": "{version}"
    }
  }
}
```

--------------------------------

### Configure Monorepo Dependency Tracking

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Sets up target defaults and project-specific versioning executors to ensure dependencies are tracked and bumped in the correct order.

```json
{
  "targetDefaults": {
    "version": {
      "dependsOn": ["^version"],
      "parallelism": false
    }
  },
  "projects": {
    "shared": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "trackDeps": true,
            "push": true
          }
        }
      }
    },
    "lib-a": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "trackDeps": true,
            "push": true
          }
        }
      }
    },
    "lib-b": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "trackDeps": true,
            "push": true
          }
        }
      }
    }
  }
}
```

--------------------------------

### runExecutor(options: GithubExecutorSchema)

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/github-executor.md

Executes the GitHub release creation process using the provided configuration options.

```APIDOC
## runExecutor(options: GithubExecutorSchema)

### Description
Creates a GitHub release and manages release artifacts as a post-target in the versioning workflow. It wraps the `gh release create` command.

### Parameters
- **tag** (string) - Required - Git tag name for the release (e.g., 'v1.0.0')
- **files** (string[]) - Optional - Asset files to attach to the release
- **notes** (string) - Optional - Release notes body text
- **notesFile** (string) - Optional - Path to file containing release notes
- **target** (string) - Optional - Target commit/branch for the release
- **draft** (boolean) - Optional - Create as draft release (not published)
- **title** (string) - Optional - Release title
- **prerelease** (boolean) - Optional - Mark as pre-release
- **discussionCategory** (string) - Optional - GitHub discussion category for this release
- **repo** (string) - Optional - Repository in format owner/repo (defaults to current)
- **generateNotes** (boolean) - Optional - Auto-generate release notes from commits
- **notesStartTag** (string) - Optional - Previous tag for auto-generated notes comparison

### Return Value
- **success** (boolean) - Returns true if the GitHub release was created successfully, false if the gh CLI command failed.

### Environment Requirements
- GITHUB_TOKEN environment variable must be set
- gh CLI must be installed
- Must be executed within a git repository
```

--------------------------------

### Execute Versioning Commands

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Commands to trigger versioning for either synchronized workspace releases or independent plugin releases.

```bash
# Sync workspace release
nx run workspace:version --push

# Independent plugin release
nx run plugin-a:version --push
```

--------------------------------

### Configure Single Package with GitHub Release

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Defines the version, publish, and github targets for a single library project.

```json
{
  "projects": {
    "my-lib": {
      "targets": {
        "build": {
          "executor": "@nx/js:tsc"
        },
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "push": true,
            "baseBranch": "main",
            "postTargets": ["build", "publish", "github"],
            "tagPrefix": "v"
          }
        },
        "publish": {
          "executor": "ngx-deploy-npm:deploy",
          "options": {
            "access": "public"
          }
        },
        "github": {
          "executor": "@jscutlery/semver:github",
          "options": {
            "tag": "{tag}",
            "title": "Release {version}",
            "notes": "{notes}",
            "generateNotes": true,
            "notesStartTag": "{previousTag}"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Configure GitHub Release with post-targets

Source: https://github.com/jscutlery/semver/blob/main/packages/semver/src/executors/github/README.md

Integrate the github executor into your nx.json configuration using post-targets. This allows it to be triggered automatically after a versioning task.

```json
{
  "targets": {
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "postTargets": ["my-project:github"]
      }
    },
    "github": {
      "executor": "@jscutlery/semver:github",
      "options": {
        "tag": "${tag}",
        "notesFile": "./libs/my-project/CHANGELOG.md"
      }
    }
  }
}
```

--------------------------------

### GitLab CI/CD Pipeline Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Automates versioning and publishing steps within a GitLab CI pipeline.

```yaml
stages:
  - version
  - publish

version:
  stage: version
  image: node:18
  before_script:
    - git config --global user.name "GitLab Bot"
    - git config --global user.email "gitlab-bot@example.com"
    - git remote set-url origin "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${CI_PROJECT_PATH}.git"
  script:
    - npm ci
    - npx nx run workspace:version --push
    - git tag -f last-release
    - git push origin last-release --force -o ci.skip
  only:
    - main
  when: manual

publish:
  stage: publish
  image: node:18
  script:
    - npm ci
    - npx nx run workspace:publish
  only:
    - tags
```

--------------------------------

### Migrate to Nx Release

Source: https://github.com/jscutlery/semver/blob/main/README.md

Executes the generator to remove existing @jscutlery/semver configuration and set up Nx Release. Manual adjustments may be required for complex configurations.

```bash
nx g @jscutlery/semver:migrate-nx-release
```

--------------------------------

### Configure GitHub Release with dynamic notes

Source: https://github.com/jscutlery/semver/blob/main/packages/semver/src/executors/github/README.md

Configure the github executor to use dynamically generated release notes by leveraging the 'notes' context from the version executor. This ensures only new changes are included in the release notes.

```json
{
  "targets": {
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "postTargets": ["my-project:github"]
      }
    },
    "github": {
      "executor": "@jscutlery/semver:github",
      "options": {
        "tag": "${tag}",
        "notes": "${notes}"
      }
    }
  }
}
```

--------------------------------

### Configure post-release targets

Source: https://github.com/jscutlery/semver/blob/main/README.md

Defines multiple targets to execute automatically after a successful version release, such as publishing to npm or creating a GitHub release.

```jsonc
{
  "targets": {
    "build": {
      /* ... */
    },
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "push": true,
        "postTargets": ["build", "npm", "github"],
      },
    },
    "github": {
      "executor": "@jscutlery/semver:github",
      "options": {
        "tag": "{tag}",
        "notes": "{notes}",
      },
    },
    "npm": {
      "executor": "ngx-deploy-npm:deploy",
      "options": {
        "access": "public",
        "distFolderPath": "dist/packages/my-package",
      },
    },
  },
}
```

--------------------------------

### Configure Release Candidate Pipeline

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Defines separate targets for RC and stable releases with post-execution targets.

```json
{
  "rc": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "releaseAs": "prerelease",
      "preid": "rc",
      "postTargets": ["publish-rc"]
    }
  },
  "release": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "releaseAs": "patch",
      "postTargets": ["publish"]
    }
  }
}
```

```bash
# Create RC
nx run lib:rc --push

# Test RC, then promote to stable
nx run lib:release --push
```

--------------------------------

### Configure GitHub Actions for Versioning

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

Use this configuration in a GitHub Actions workflow to provide the necessary authentication token for the versioning command.

```yaml
- name: Version
  run: nx run workspace:version --push
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Workspace-level sync mode configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

Enables workspace-level versioning by setting syncVersions to true in the project configuration.

```json
{
  "projects": {
    "workspace": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "syncVersions": true,
            "tagPrefix": "v"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/README.md

Visual representation of the package source code organization.

```text
packages/semver/
├── src/
│   ├── executors/
│   │   ├── version/           # Version executor
│   │   ├── github/            # GitHub executor
│   │   ├── gitlab/            # GitLab executor
│   │   └── common/            # Shared utilities
│   ├── generators/
│   │   └── install/           # Install generator
│   └── index.ts               # Entry point
├── executors.json             # Executor definitions
├── generators.json            # Generator definitions
├── package.json
└── CHANGELOG.md
```

--------------------------------

### Configure GitHub Release Executor

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

Basic and advanced configurations for the GitHub release executor.

```json
{
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "title": "Release {version}",
      "notes": "{notes}"
    }
  }
}
```

```json
{
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "title": "{projectName} {version}",
      "generateNotes": true,
      "notesStartTag": "{previousTag}",
      "files": ["dist/**/*.tar.gz", "dist/**/*.zip"]
    }
  }
}
```

--------------------------------

### Dry-Run Versioning with Nx

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Use the --dryRun flag to simulate versioning, changelog generation, and commit messages without modifying the git repository.

```bash
# See what would happen
nx run lib:version --dryRun

# View proposed changelog, version, commit message
# No git changes made
```

--------------------------------

### Default Version Executor Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

The minimal configuration required for the version executor, requiring only the postTargets array.

```json
{
  "targets": {
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "postTargets": []
      }
    }
  }
}
```

--------------------------------

### Retrieve project version information

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/version-calculation.md

Fetches the last version, commit history, and git reference for a specific project.

```typescript
const versionInfo = await getProjectVersion({
  tagPrefix: 'lib-',
  projectRoot: 'packages/lib',
  projectName: 'lib',
});
// Returns:
// {
//   lastVersion: '1.0.0',
//   commits: ['feat: add new API', 'fix: bug in parser'],
//   lastVersionGitRef: 'lib-1.0.0'
// }
```

--------------------------------

### writeFile(filePath: string, data: string | Buffer): Promise<void>

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/utilities.md

Writes data to a file.

```APIDOC
## writeFile(filePath: string, data: string | Buffer)

### Description
Writes the provided data to a file at the specified path using UTF-8 encoding. The file is created if it does not exist, or overwritten if it does.

### Parameters
- **filePath** (string) - Required - Destination file path.
- **data** (string | Buffer) - Required - Content to write to the file.

### Response
- **Promise<void>** - Resolves when the file has been successfully written.
```

--------------------------------

### Define Versioning Executors in project.json

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Configures the version and github executors to automate tagging and release notes generation.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "push": true,
      "postTargets": ["github"],
      "tagPrefix": "{projectName}@"
    }
  },
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "title": "{projectName} {version}",
      "notes": "{notes}"
    }
  }
}
```

--------------------------------

### Execute Monorepo Release

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Commands to version affected packages or a specific project in a monorepo.

```bash
# Version affected packages only
nx affected --base=last-release --target=version --parallel=1 --push

# Or version specific project
nx run lib-a:version --push
```

--------------------------------

### Link Library Locally with pnpm

Source: https://github.com/jscutlery/semver/blob/main/CONTRIBUTING.md

Steps to link the built library globally using pnpm for local development in another project. This involves navigating to the built package directory and then linking it globally.

```sh
cd dist/packages/semver
pnpm link --global
```

```sh
pnpm link --global @jscutlery/semver
```

--------------------------------

### Dry-run Verification Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

Enables dry-run mode to preview changes without applying them to the repository.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "dryRun": true
    }
  }
}
```

--------------------------------

### formatTagPrefix

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/utilities.md

Generates a tag prefix string based on project configuration, sync mode, and optional custom prefixes.

```APIDOC
## formatTagPrefix(options: { versionTagPrefix?: string; projectName: string; syncVersions: boolean }): string

### Description
Generates a tag prefix string. If a custom prefix is provided, it is used; otherwise, it defaults to 'v' for synced versions or '{projectName}-' for independent projects.

### Parameters
- **versionTagPrefix** (string | null | undefined) - Optional - Custom tag prefix or null to disable; supports template strings
- **projectName** (string) - Required - Nx project name
- **syncVersions** (boolean) - Required - Whether versioning is synced across projects

### Return Value
- **string** - Formatted tag prefix string.

### Example
```typescript
formatTagPrefix({
  versionTagPrefix: undefined,
  projectName: "my-lib",
  syncVersions: false
});
// Returns: "my-lib-"
```
```

--------------------------------

### Configure Publish to npm with GitHub Release

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/README.md

Defines executors for versioning, building, publishing, and creating GitHub releases within an Nx project configuration.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "push": true,
      "baseBranch": "main",
      "postTargets": ["build", "publish", "github"]
    }
  },
  "build": {
    "executor": "@nx/js:tsc"
  },
  "publish": {
    "executor": "ngx-deploy-npm:deploy"
  },
  "github": {
    "executor": "@jscutlery/semver:github",
    "options": {
      "tag": "{tag}",
      "title": "Release {version}",
      "notes": "{notes}"
    }
  }
}
```

--------------------------------

### GitHub Release CI/CD Workflow

Source: https://github.com/jscutlery/semver/blob/main/packages/semver/src/executors/github/README.md

Set up a GitHub Actions workflow to automate versioning and GitHub releases. Ensure the GITHUB_TOKEN is provided as an environment secret.

```yaml
- name: Version
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: npx nx affected --target=version
```

--------------------------------

### Push with npm Auth Verification

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

Configures automatic pushing of changes and verifies npm authentication before proceeding.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "push": true,
      "verifyNpmAuth": true,
      "baseBranch": "main"
    }
  }
}
```

--------------------------------

### Invalid and Valid ReleaseIdentifier Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/errors.md

Demonstrates the difference between an unsupported releaseAs value and a valid one.

```json
{
  "releaseAs": "stable"  // ❌ Not valid
}
```

```json
{
  "releaseAs": "minor"  // ✅ Valid
}
```

--------------------------------

### getProjectVersion(options)

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/version-calculation.md

Retrieves the last version, commit history, and git reference for a specific project based on tag prefixes.

```APIDOC
## getProjectVersion(options)

### Description
Queries git for tags matching a prefix, retrieves commits since the last tag, and returns versioning metadata for a project.

### Parameters
- **tagPrefix** (string) - Required - Prefix for filtering git tags
- **projectRoot** (string) - Required - Project directory path
- **releaseType** (ReleaseIdentifier) - Optional - For future compatibility
- **since** (string) - Optional - Git ref to start commit history from
- **projectName** (string) - Required - Project name for logging
- **preid** (string) - Optional - Prerelease identifier

### Response
- **lastVersion** (string) - Previous version from last matching tag
- **commits** (string[]) - Array of commit bodies since last version
- **lastVersionGitRef** (string) - Git reference for the last version tag
```

--------------------------------

### formatTag

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/utilities.md

Combines a tag prefix and a semantic version string to create a complete git tag.

```APIDOC
## formatTag(options: { tagPrefix: string; version: string }): string

### Description
Concatenates the provided tag prefix and semantic version to produce a standard git tag string.

### Parameters
- **tagPrefix** (string) - Required - Tag prefix generated from formatTagPrefix
- **version** (string) - Required - Semantic version string

### Return Value
- **string** - Complete git tag string.

### Example
```typescript
formatTag({
  tagPrefix: "v",
  version: "1.2.3"
});
// Returns: "v1.2.3"
```
```

--------------------------------

### Configure custom preset with GitLab URLs

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/configuration.md

Define a custom preset object to override default commit, compare, and issue URL formats.

```json
{
  "version": {
    "executor": "@jscutlery/semver:version",
    "options": {
      "preset": {
        "name": "conventionalcommits",
        "commitUrlFormat": "{{host}}/{{owner}}/{{repository}}/commit/{{hash}}",
        "compareUrlFormat": "{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}",
        "issueUrlFormat": "{{host}}/{{owner}}/{{repository}}/issues/{{id}}"
      }
    }
  }
}
```

--------------------------------

### Force Release Configuration

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/errors.md

Use this configuration option to allow a patch version bump even when no changes are detected since the last release.

```json
{
  "options": {
    "allowEmptyRelease": true
  }
}
```

--------------------------------

### Configure GitLab Release Target

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/integration-patterns.md

Project configuration for integrating versioning with GitLab releases.

```json
{
  "projects": {
    "workspace": {
      "targets": {
        "version": {
          "executor": "@jscutlery/semver:version",
          "options": {
            "syncVersions": true,
            "push": true,
            "baseBranch": "main",
            "postTargets": ["gitlab"]
          }
        },
        "gitlab": {
          "executor": "@jscutlery/semver:gitlab",
          "options": {
            "tag": "{tag}",
            "name": "Release {version}",
            "description": "{notes}"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Customize conventional changelog preset

Source: https://github.com/jscutlery/semver/blob/main/README.md

Override preset variables like URL formats and commit types to support platforms like GitLab.

```json
{
  "executor": "@jscutlery/semver:version",
  "options": {
    "preset": {
      "commitUrlFormat": "{{host}}/{{owner}}/{{repository}}/commit/{{hash}}",
      "compareUrlFormat": "{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}",
      "issueUrlFormat": "{{host}}/{{owner}}/{{repository}}/issues/{{id}}",
      "types": [
        { "type": "feat", "section": "✨ Features" },
        { "type": "fix", "section": "🐞 Bug Fixes" },
        { "type": "chore", "hidden": true }
      ]
    }
  }
}
```

--------------------------------

### Define PresetOpt type

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/types.md

Allows either a pre-built preset name or a custom configuration object.

```typescript
export type PresetOpt = Preset | Record<string, any>;
```

--------------------------------

### Version Projects in Independent Mode

Source: https://github.com/jscutlery/semver/blob/main/_autodocs/api-reference/installation-generator.md

Commands to version a specific project or all affected projects in independent mode.

```bash
nx run lib-a:version --push
```

```bash
nx affected --target=version --base=last-release --parallel=1
```