Skip to content

Latest commit

 

History

History
102 lines (70 loc) · 4.71 KB

SETTING_UP.md

File metadata and controls

102 lines (70 loc) · 4.71 KB
Raw

Setting up an existing Elixir project

Before we begin

semantic-release uses git tags to determine the current version of a project, so you must make sure your latest version is tagged (and pointing to the right commit).

If you are using a different tag format than v${version}, see the tagFormat option.

If your current release is an alpha or beta release, you must also add a Git note so that Semantic Release recognizes it correctly, for example:

git notes --ref semantic-release add -f -m '{"channels":["alpha"]}' v1.0.0-alpha.1
git push origin refs/notes/semantic-release

Install Node.js

You'll need Node.js >=18.17.

The recommended way to install it is with the asdf version manager (which also supports Elixir) by adding it to your .tool-versions and running asdf install.

Otherwise, you can download it from nodejs.org.

Install the tools

Install the required libraries:

npm i --save-dev semantic-release @semantic-release/changelog @semantic-release/git semantic-release-hex

Add node_modules to your .gitignore:

echo -e "\n# Node.js dependencies directory\nnode_modules" >> .gitignore

Configuring semantic-release

semantic-release is modular, extendable and configurable to your preferences. Here we'll setup a workflow for the main branch with the following steps:

  1. Analyze the commits to determine the version bump type (if any)
  2. Generate release notes from the commits
  3. Write the release notes to the CHANGELOG.md file
  4. Bump the version in mix.exs
  5. Create and push a release commit (with the updated CHANGELOG.md and mix.exs files)
  6. Create a release tag
  7. Create a GitHub release

There's a few ways to configure semantic-release, but we'll chose to do it in package.json to avoid creating an extra file. Add a release key as follow:

{
  "devDependencies": {...},

  "release": {
    "branches": ["main"],
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      "@semantic-release/changelog",
      "semantic-release-hex",
      [
        "@semantic-release/git",
        {
          "assets": ["CHANGELOG.md", "mix.exs"],
          "message": "chore(release): v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
        }
      ],
      "@semantic-release/github"
    ]
  }
}

Note: if you want your CHANGELOG to include all commit types (and add a bit of color with category emojis) like the one in this demo, checkout @insurgent/conventional-changelog-preset.

CI configuration (GitHub Actions)

See semantic-release documentation on CI configuration for general information.

See examples/release.yml and examples/test.yml for example workflows in an Elixir project.

If you use branch protection: See comments in example release workflow. To generate the CI_GITHUB_TOKEN secret needed to bypass branch protection when pushing the release commit, see this StackOverflow answer on how to create a fine-grained token with the right scopes (I know, I really need to update the docs).

Running from the CLI

Note: If you're concerned about security, you can run gh auth refresh after using gh auth token to regenerate gh's token and invalidate the previous one (or you can create a fine-grained token by visiting the StackOverflow link in CI configuration).

To test everything is working

GH_TOKEN=$(gh auth token) npx semantic-release --dry-run

To make an actual release

GH_TOKEN=$(gh auth token) npx semantic-release --no-ci

Note: if your git is configured to automatically sign tags, this won't work due to a known issue. Run git config tag.gpgSign false in your repo first.