# Introduction

Fully automated version management and release workflow for PowerShell modules. Inspired by the popular [semantic-release](https://github.com/semantic-release/semantic-release), **PSSemanticRelease** automates version determination, changelog generation, Git tagging, and optional publishing to GitHub, GitLab, and module registries.

[![PowerShell Gallery](https://img.shields.io/powershellgallery/v/PSSemanticRelease?label=version)](https://www.powershellgallery.com/packages/PSSemanticRelease)

***

## Key Features

* **Automatic semantic versioning** based on commit messages.
* **Changelog and release notes generation**.
* **Git tagging** and optional **GitHub/GitLab release** creation.
* **Publish modules** to PSGallery or NuGet.
* **DryRun mode** for safe testing without impacting your repository.
* **Extensible architecture** via plugins and custom scripts.

***

## How It Works

**PSSemanticRelease** inspects your commit messages to determine how to bump the version—**major**, **minor**, or **patch**—following semantic versioning rules. By default, it uses the [Conventional Commits](https://www.conventionalcommits.org/) specification.

| Commit message                                      | Release type                    |
| --------------------------------------------------- | ------------------------------- |
| `fix(parser): handle multi-line comments correctly` | Patch release                   |
| `feat(cli): add --verbose flag to Get-ModuleInfo`   | Minor release                   |
| `refactor(build): simplify release script logic`    | *no release*                    |
| `feat(api)!: remove deprecated Invoke-OldCommand`   | Major release (breaking change) |

***

## Extensible with Plugins

The real power of **PSSemanticRelease** lies in its extensibility. The release workflow is a series of steps, and each step is handled by one or more plugins. You can customize the entire process by adding or removing plugins in your `semantic-release.json` configuration file.

### Core Plugins

**PSSemanticRelease** ships with a suite of official plugins to handle the most common release tasks:

| Plugin                                         | Description                                                             |
| ---------------------------------------------- | ----------------------------------------------------------------------- |
| **@ps-semantic-release/CommitAnalyzer**        | Determines the release type (major, minor, patch) from commit messages. |
| **@ps-semantic-release/ReleaseNotesGenerator** | Generates changelog content from the analyzed commits.                  |
| **@ps-semantic-release/Changelog**             | Updates the `CHANGELOG.md` file with the new release notes.             |
| **@ps-semantic-release/Git**                   | Commits changes and pushes to your remote repository.                   |
| **@ps-semantic-release/GitHub** / **GitLab**   | Creates a release on GitHub or GitLab, including release notes.         |
| **@ps-semantic-release/NuGet**                 | Publishes your PowerShell module to a NuGet-based repository.           |
| **@ps-semantic-release/Exec**                  | Allows you to run custom scripts at any stage of the release process.   |

> For detailed plugin configuration, see the [Plugins documentation](https://ps-semantic-release.gitbook.io/ps-semantic-release/usage/plugins).

***

## Release Flow

A **PSSemanticRelease** run goes through the following phases, executed by the configured plugins:

| Step               | Description                                                             |
| ------------------ | ----------------------------------------------------------------------- |
| `VerifyConditions` | Checks that your environment, credentials, and configuration are valid. |
| `AnalyzeCommits`   | Scans commits to determine the next release type.                       |
| `VerifyRelease`    | Optional validations to ensure the release can proceed safely.          |
| `GenerateNotes`    | Generates release notes from commit history.                            |
| `Prepare`          | Updates module manifests, changelogs, or runs preparation scripts.      |
| `Publish`          | Pushes Git tags, commits, and publishes artifacts.                      |

> This workflow mirrors the official [semantic-release](https://semantic-release.gitbook.io/semantic-release/#release-steps) pipeline.

***

## Getting Started

Ready to automate your releases?

1. [**Installation**](https://ps-semantic-release.gitbook.io/ps-semantic-release/usage/installation): Add **PSSemanticRelease** to your project.
2. [**Configuration**](https://ps-semantic-release.gitbook.io/ps-semantic-release/usage/configuration): Create your `semantic-release.json` file.
3. [**CI Setup**](https://ps-semantic-release.gitbook.io/ps-semantic-release/usage/ci-configuration): Integrate it into your CI/CD pipeline (e.g., GitHub Actions).