easy-release

easy-release is a simpler way to release software. It is a pair of GitHub Actions that help maintain a simple changelog and generate automated releases. One Action uses comments on newly created Pull Requests to prompt for changelogs. Another can be used to cut new releases with versioning based on the changelogs accumulated since the previous release.

easy-release provides a way to do changelog and release management without imposing rules on your development process. We believe that commit messages and release notes are written with different audiences in mind and we don't try to use one to solve the other.

easy-release implicitly encourages frequent releases. We believe that releasing eagerly and often is an important part of a tight feedback loop between maintainers and users and we want to reduce the friction associated with releases.

How It Works

easy-release is installed as a pair of Actions in your GitHub repo. One action will prompt you for release notes on each PR, the other will create a new GitHub release and tag for you.

Changelogs

The easy-release-changelog Action leaves comments on new Pull Requests to prompt authors to create release notes. When a new PR is created, the action runs and leaves a comment asking you to specify the type of change and a description for the change. The Pull Request author edits the comment to select a change type and to author a description and then adds the generate-changelog label to the PR to cause the action to rerun and add a changelog file to the changeset.

easy-release maintains a changelog directory at the root of the repository that contains all of the release notes generated by the Action. It organizes these into directories for each version of the software released, and also maintains an unreleased directory for changes pending release.

If you are authoring a change that does not need a changelog you can instead add the no-changelog label to your Pull Request and the Action will not prompt you for a release note on that change. This is particularly useful for automated Pull Requests such as those from Dependabot.

Supported changelog types are:

• improvement
• fix
• break
• deprecation

Version bump rules:

• break -> major
• improvement -> minor
• everything else -> patch

Releases

The easy-release-publish Action creates a new GitHub release and corresponding tag based on the currently unreleased changelogs. Maintainers can kick off the Action manually or it can be scheduled to run on some cadence.

The Action inspects your unreleased release notes and calculates the next version to release based on the types of those release notes and the previously released version. easy-release supports both Semantic Versioning and a simple incremental versioning scheme.

The easy-release-publish Action does the heavy lifting of maintaining the changelog directory, and will move all unreleased release notes to the newly created version directory as part of the release process.

The release action supports two versioning schemes:

• semver calculates major.minor.patch versions from the changelog entry types.
• simple ignores the bump category for numbering and increments integer versions: 1, 2, 3.

If there are no unreleased changelog entries, the publish action still creates an empty release. simple versions increment by one, and semver versions use a minor bump.

Configuration

An easy-release configuration file is also required at .easy-release/config.yml:

easy-release:
  versionScheme: semver
  versionPrefix: ""

easy-release can be configured to use simple integer versions instead of Semantic Versioning.

easy-release:
  versionScheme: simple
  versionPrefix: ""

Releases can be prefixed e.g. v1.2.3 or v1. Version prefixes may only contain letters and hyphens.

easy-release:
  versionScheme: semver
  versionPrefix: v

Git tags are the canonical version history. If no previous matching tag exists, the first release is 1 for simple or 0.0.1 for semver. If the most recent tag with the configured prefix does not match the configured version scheme, the release action fails unless EASY_RELEASE_TARGET_VERSION is set.

To force a specific release version for onboarding or a planned version jump, create a repository Actions variable named EASY_RELEASE_TARGET_VERSION. The release action checks for that variable automatically. The value should be the raw version without the configured prefix, e.g. 3 or 1.0.0, not v3 or v1.0.0. The release action will fail if that target version already exists as a Git tag.

Installation

Create a config file described above at .easy-release/config.yml and then create these GitHub Actions workflow files in your respository.

.github/workflows/easy-release-changelog.yml:

name: easy-release-changelog

on:
  pull_request_target:
    types: [opened, reopened, labeled]
    branches: [main]

permissions:
  contents: write
  issues: write
  pull-requests: write

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: nickcharles/easy-release/actions/changelog@v8

.github/workflows/easy-release-publish.yml:

name: easy-release-publish

on:
  workflow_dispatch:
  pull_request_target:
    types: [closed]

permissions:
  actions: read
  contents: write

jobs:
  run:
    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' || (github.event.pull_request.merged == true && github.event.pull_request.base.ref == github.event.repository.default_branch && contains(github.event.pull_request.labels.*.name, 'easy-release')) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
          ref: ${{ github.event.repository.default_branch }}

      - uses: nickcharles/easy-release/actions/release@v8

To publish on a schedule, add a schedule trigger to .github/workflows/easy-release-publish.yml. GitHub cron schedules use UTC. This example runs every Monday at 16:00 UTC:

on:
  workflow_dispatch:
  pull_request_target:
    types: [closed]
  schedule:
    - cron: "0 16 * * 1"