Learning Semantic Release

Learning Semantic Release

What is it?

Semantic Release is a tool made to run in CI servers (or locally if you're brave enough) and generate a new version of your project. It analyzes the commit rules/patterns from your project and based on it can create a new git tag version, new release and even changelog files

Installation

This is the "hard" way, it just adds the dependencies and you need to set the build options manually...

  npm install semantic-release -D

But this tool have an amazing interactive CLI, so you can run

  npx semantic-release-cli setup

This might add at your package.json file the required scripts and rules to run it properly

Configuration

This package is very permissive and lets you pack your things through different files like:

package.json with the release key
.releaserc.(yaml|yml|json|js|cjs)
release.config.(js|cjs)

For this project I just used package.json file with the release key config

  "release": {
    "branches": [
      "main"
    ],
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      "@semantic-release/npm",
      "@semantic-release/github"
    ],
    "repositoryUrl": "https://github.com/odonatojunior/learning-semantic-release",
    "publish": [
      "@semantic-release/github"
    ]
  }

`branches`

The releases will happen on the branches specified inside this array

`plugins`

A list of plugins that can have configuration inside each item. The docs mention that these config can be "defined by wrapping the name and an options object in an array"

`repositoryUrl`

Your GitHub repository url (the name is self explanatory)

Plugins

If you can notice there's a key publish that I didn't mention before at configuration. Well, I found this key reading an issue because this repository pipeline couldn't generate a release at GitHub. And I'll update to the proper way when I finish this documentation 👀

@semantic-release/commit-analyzer

There are tons of commit presets around the internet and every team or company has chose one to work with, so this is where you can tell semantic-release your commit preset.

The supported presets are:

angular
atom
codemirror
ember
eslint
express
jquery
jshint
conventionalcommits

The default preset is angular, it's the one that I commonly (try) to use inside my projects.

@semantic-release/release-notes-generator

Some of the configuration inside commit-analyzer can be shared inside release-notes-generator too. It will use your commit history to generate the release notes/changelog. These two plugins complement each other job

@semantic-release/github

When the release job is done semantic-release will need this plugin to publish a new package inside your repository. You'll need to add the publish step on your release object to publish a new release inside your repo

You can learn more about packages by reading this article and about releases reading this one.

The automated release is failing 🚨

🚨 The automated release from the `main` branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the main branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here are some links that can help you:

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

Cannot push to the Git repository.

semantic-release cannot push the version tag to the branch main on the remote Git repository with URL https://x-access-token:[secure]@github.com/odonatojunior/learning-semantic-release.

This can be caused by:

a misconfiguration of the repositoryUrl option
the repository being unavailable
or missing push permission for the user configured via the Git credentials on your CI environment

Good luck with your project ✨

Your semantic-release bot 📦🚀

odonatojunior / learning-semantic-release Goto Github PK