semantic-release / semantic-release

:package::rocket: Fully automated version management and package publishing

📦🚀 semantic-release

Fully automated version management and package publishing

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package.

This removes the immediate connection between human emotions and version numbers, strictly following the Semantic Versioning specification and communicating the impact of changes to consumers.

Trust us, this will change your workflow for the better. – egghead.io

Highlights

• Fully automated release
• Enforce Semantic Versioning specification
• New features and fixes are immediately available to users
• Notify maintainers and users of new releases
• Use formalized commit message convention to document changes in the codebase
• Publish on different distribution channels (such as npm dist-tags) based on git merges
• Integrate with your continuous integration workflow
• Avoid potential errors associated with manual releases
• Support any package managers and languages via plugins
• Simple and reusable configuration via shareable configurations
• Support for npm package provenance that promotes increased supply-chain security via signed attestations on GitHub Actions

How does it work?

Commit message format

semantic-release uses the commit messages to determine the consumer impact of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog and publishes the release.

By default, semantic-release uses Angular Commit Message Conventions. The commit message format can be changed with the preset or config options of the @semantic-release/commit-analyzer and @semantic-release/release-notes-generator plugins.

Tools such as commitizen or commitlint can be used to help contributors and enforce valid commit messages.

The table below shows which commit message gets you which release type when semantic-release runs (using the default configuration):

Commit message	Release type
fix(pencil): stop graphite breaking when too much pressure applied	Patch Fix Release
feat(pencil): add 'graphiteWidth' option	Minor Feature Release
perf(pencil): remove graphiteWidth option BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons.	Major Breaking Release (Note that the BREAKING CHANGE: token must be in the footer of the commit)

Automation with CI

semantic-release is meant to be executed on the CI environment after every successful build on the release branch. This way no human is directly involved in the release process and the releases are guaranteed to be unromantic and unsentimental.

Triggering a release

For each new commit added to one of the release branches (for example: master, next, beta), with git push or by merging a pull request or merging from another branch, a CI build is triggered and runs the semantic-release command to make a release if there are codebase changes since the last release that affect the package functionalities.

semantic-release offers various ways to control the timing, the content and the audience of published releases. See example workflows in the following recipes:

• Using distribution channels
• Maintenance releases
• Pre-releases

Release steps

After running the tests, the command semantic-release will execute the following steps:

Step	Description
Verify Conditions	Verify all the conditions to proceed with the release.
Get last release	Obtain the commit corresponding to the last release by analyzing Git tags.
Analyze commits	Determine the type of release based on the commits added since the last release.
Verify release	Verify the release conformity.
Generate notes	Generate release notes for the commits added since the last release.
Create Git tag	Create a Git tag corresponding to the new release version.
Prepare	Prepare the release.
Publish	Publish the release.
Notify	Notify of new releases or errors.

Requirements

In order to use semantic-release you need:

• To host your code in a Git repository
• Use a Continuous Integration service that allows you to securely set up credentials
• A Git CLI version that meets our version requirement installed in your Continuous Integration environment
• A Node.js version that meets our version requirement installed in your Continuous Integration environment

Documentation

• Usage
  • Getting started
  • Installation
  • CI Configuration
  • Configuration
  • Plugins
  • Workflow configuration
  • Shareable configurations
• Extending
  • Plugins
  • Shareable configuration
• Recipes
  • CI configurations
  • Git hosted services
  • Release workflow
• Developer guide
  • JavaScript API
  • Plugins development
  • Shareable configuration development
• Support
  • Resources
  • Frequently Asked Questions
  • Troubleshooting
  • Node version requirement
  • Node Support Policy

Get help

• GitHub Discussions
• Stack Overflow
• Twitter

Badge

Let people know that your package is published using semantic-release and which commit-convention is followed by including this badge in your readme.

[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)

Team

Gregor Martynus	Pierre Vanduynslager	Matt Travi

Alumni

Stephan Bönnemann	Rolf Erik Lekang	Johannes Jörg Schmidt	Finn Pauls	Christoph Witzko

semantic-release's Issues

Pre.js unit test are very broken.

As I discovered with lots and lots of debugging while working on #60, the unit tests for pre.js (test/specs/pre.js) are badly broken.

With the old commit-analyzer API, the commit-analyzer would be called, and could trigger a release, even if no commits were present. For this reason, no body realized that pre.js was not actually stubbing child_process, the commit-analyzer was being called anyway.

Well, with the new API, the commit-analyzer is only called when needed, so the mocking has to work. Unfortunately, it doesn't.

I'm not really sure how the tests should be redone, AFAIK, proxyquire sandboxes the module, so the mock won't trickle down into commit.js. So I decided to open this to discuss it.

cc @boennemann

"Plugin" or "hook" system

There are two uses for custom hooks I can currently think of:
Custom verification for the release (e.g. #7) and manipulation of the changelog/codenames.

I could imagine something like this: One has to define the verifyrelease and/or the changelog scripts inside the package.json. semantic-release sends some information over stdin and uses stdout/exit codes to process the information generated.

Write an nsp verifyConditions plugin

The nodesecurity project offers the nsp module, which allows you to audit a package.json and find security vulnerabilities.

I'd love to see a semantic-release verifyConditions plugin (just like condition-travis) that aborts any release where there are security vulnerabilities in the dependencies, but I might not immediately have the time to do it myself.

If you want to give this a shot let me know in this issue and I'm happy to help wherever I can. You can reach me in the semantic-release gitter room, or on Twitter.

test: no cleanup for `npm link`

Should we have some sort of Commitizen integration?

I just found out about commitizen: http://commitizen.github.io/cz-cli/, it seems perfect for semantic-release, and perhaps we should integrate with it in some way. I'm just opening this issue for discussion.

Bower Support for libraries

I just realized that (if I'm not mistaken) this fails to push the built version of the library to the tagged commit. This is not good for people who use my library via bower (as much as I hate it). Is there any way that as part of the post action, semantic-release could commit whatever's changed (built files) and push those up to the tag on the repository? This way people using bower can get my library's built files.

Write an istanbul verifyConditions plugin

The popular code coverage generator istanbul offers the check-coverage command.

I'd love to see a semantic-release verifyConditions plugin (just like condition-travis) that aborts any release where defined coverage thresholds aren't met, but I might not immediately have the time to do it myself.

If you want to give this a shot let me know in this issue and I'm happy to help wherever I can. You can reach me in the semantic-release gitter room, or on Twitter.

Gitlab support

By now only github releases are supported. What do you think about adding gitlab support or at least make the release system pluggable.

throws error when git remote origin is not set

Great opportunity for a better error message / guidance here :)

$ ./node_modules/.bin/semantic-release setup

/Users/gregor/Projects/debug-couchdb-view/node_modules/semantic-release/src/setup.js:29
    var repo = config['remote "origin"'].url
                                        ^
TypeError: Cannot read property 'url' of undefined

If semantic release fails (due to npm publish error) should travis fail?

As per subject.

Breaking change detection

This an idea that I wanted to build for a long time and with the latest npm weekly I have a proof of concept how it could be done: https://gist.github.com/chrisdickinson/ba532fa0e4e243fb7b44

Here is my rough idea of how this could work:

1. Assumptions: All test related files lie in a tests/ subfolder, npm test is the test command, latest tag is pulled, dependencies are installed
2. Checkout the tests subfolder and package.json of the last release
3. Install only the devDependencies of the last release
4. Execute npm test; if it fails it's a breaking change

This could be executed in the prepublish step. Another idea would be to only execute this when a release is due, but no breaking change has been marked. If it fails this doesn't automatically release a new major version, but it fails and tells the user to rewrite the commit messages to correctly mark the breaking change including migration instructions.

npm Could not pack error

(Sorry in advance for filing an issue on this; I couldn't find a better channel).

I'm trying to add semantic-release to https://github.com/angular-pouchdb/angular-pouchdb, but am running into:

npm ERR! addLocalDirectory Could not pack /home/travis/build/angular-pouchdb/angular-pouchdb to /home/travis/.npm/angular-pouchdb/0.0.0-semantically-released/package.tgz

(Full Travis CI log).

I can't reproduce this error locally. Have you ran into this?

NB, angular-pouchdb has had previous releases/tags; I'm adding semantic-release at angular-pouchdb v2.0.1. Would this trigger this error?

Make "Failed to determine new version." error more descriptive

You never should git push -f to master, we know, but it might happen anyway. If semantic-release cannot "determine new version" because the git commit hash it uses for it's range of commits to be parsed, then it could provide a better error message, with probably a link to FAQ on how to manually release a new version in such cases?

Here's an example
https://travis-ci.org/hoodiehq/pouchdb-hoodie-api/jobs/72318979#L5137

add `[release skip]` commit message command

Integrate with dont-break

A major problem with minor / patch releases is that they might accidentally break projects that depend on them. I have a tool dont-break https://github.com/bahmutov/dont-break that can check if your release is breaking existing users - perfect step for CI before publishing.

Decouple version determiner from npm registry

Last release is currently determined by consulting the npm registry. As mentioned (out of band), this could be made more flexible by looking at Git tags (for example).

A use case for this could be in situations where the npm publish step is undesirable. This seems to resonate with some of the discussion in #51.

npm ERR! publish Failed PUT 500

https://travis-ci.org/gr2m/moment.parseFormat/builds/64160442#L202 – any idea?

why is release name set from commit message?

see https://github.com/gr2m/moment.parseFormat/releases/tag/v1.0.0

"v1.0.0: chore: follow semver" should just be "v1.0.0". Is this a bug or by design?

jspm has some really interesting features.

Hey Stephan, look at this output:

ok   Installed babel as npm:babel-core@^5.1.13 (5.6.15)

     The following new package versions were substituted by install deduping:

       commander 2.5.1 -> 2.5.0

ok   ES6 transpiler set to babel.
ok   Loader files downloaded successfully

It's dependency handling! jspm.io

Write a dont-break verifyRelease plugin

dont-break is a very nice module by @bahmutov, that can detect breaking changes, by running your dependents tests against the current version of your code base.

I'd love to see a semantic-release verifyRelease plugin (just like cracks), but I might not immediately have the time to do it myself.

If you want to give this a shot let me know in this issue and I'm happy to help wherever I can. You can reach me in the semantic-release gitter room, or on Twitter.

process.exit(1) in debug mode makes npm think there's an error

Here. It makes npm panic and output a debug log.

npm-shrinkwrap.json support

If present the version update needs to be written to the npm-shrinkwrap.json file, too.

Depending on checks performed on publish this might be relevant for the setup script, too.

Can not push to npm

npm ERR! Linux 3.13.0-40-generic
npm ERR! argv "/home/travis/.nvm/versions/io.js/v3.1.0/bin/iojs" "/home/travis/.nvm/versions/io.js/v3.1.0/bin/npm" "publish"
npm ERR! node v3.1.0
npm ERR! npm v2.14.0
npm ERR! code ENEEDAUTH
npm ERR! need auth auth required for publishing
npm ERR! need auth You need to authorize this machine using npm adduser
npm ERR! Please include the following file with any support request:
npm ERR! /home/travis/build/lapanoid/presentation/npm-debug.log
npm ERR! Linux 3.13.0-40-generic
npm ERR! argv "/home/travis/.nvm/versions/io.js/v3.1.0/bin/iojs" "/home/travis/.nvm/versions/io.js/v3.1.0/bin/npm" "run" "semantic-release"
npm ERR! node v3.1.0
npm ERR! npm v2.14.0
npm ERR! code ELIFECYCLE
npm ERR! olo-proj@ semantic-release: semantic-release pre && npm publish && semantic-release post
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the olo-proj@ semantic-release script 'semantic-release pre && npm publish && semantic-release post'.
npm ERR! This is most likely a problem with the olo-proj package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! semantic-release pre && npm publish && semantic-release post
npm ERR! You can get their info via:
npm ERR! npm owner ls olo-proj
npm ERR! There is likely additional logging output above.
npm ERR! Please include the following file with any support request:
npm ERR! /home/travis/build/lapanoid/presentation/npm-debug.log

You cannot publish over the previously published version 1.0.0

is this expected behavior?
https://travis-ci.org/hoodiehq/pouchdb-hoodie-sync/jobs/67034467#L364

I don't understand why it tries to deploy at all. There were only chore: ... commits since 1.0.0 was released?

Breaking change/major release not detected

According to conventional-changelog:

Breaking Changes are detected as such if the Body contains a line starting with BREAKING CHANGES: The rest of the commit message is then used for this.

parseRawCommit shows they match on BREAKING CHANGE, i.e. ignoring the trailing S.

Given that, in eHealthAfrica/qsl.js@0816bf9, I have the following in my commit message:

BREAKING CHANGE: qsl.parse returns a more useful formatted response, rather
than an intermediary array of objects representation.

Therefore, I would have expected semantic-release to published a major release. Instead, it published a minor. See build log.

Use npm version directly?

As mentioned in #11, this would add support for shrinkwrap.json, and it should also allow the version number to be kept in package.json, which I personally think would be a big improvement. Would love to know your thoughts.

https://docs.npmjs.com/cli/version

Write plugin to allow custom uploads to GitHub releases

For JavaScript libraries that can be used in the browser, it would be nice to have direct downloads of the different versions, ideally right from the GitHub releases page. Here is an example:
https://github.com/gr2m/initials/releases

It would be nice to be able to not only download the source code for each version, but also the built initials.js and maybe ainitials.min.js files.

Could that be with a plugin?

Use `gitHead` information from registry

In the prepublish step the git commit ref of the latest version is retrieved by complex git command execution.

However when retrieving the info from the npm registry about the last published version we also get the git ref of the last version published for free by npm :)

This simplifies the command and also removes the need to manually git fetch --tags for local preview.

throws errors when git is not initialised

$ ./node_modules/.bin/semantic-release setup

fs.js:438
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^
Error: ENOENT, no such file or directory './.git/config'

How does semantic-release know what version (major, minor, patch) to release?

add `[verification skip]` commit message command

Support multiple verifyConditions and verifyRelease plugins

docs: add GitHub token scope

In the CI Server set up, we need to add a GitHub OAuth token. Which scope(s) need to be selected here? I presume its just repo/public_repo, but it'd be nice to have that documented either way.

First release uses version 0.0.0-semantically-released

As per https://github.com/boennemann/semantic-release/issues/18#issuecomment-99531802, if the package is new (i.e. does not pre-exist on npm), packages are published with "version": "0.0.0-semantically-released". I'd expect 1.0.0 to be used here.

As a workaround, I first publish 1.0.0 manually, then add semantic-release afterwards.

Inserting `original-command && semantic-release pre` will break projects' builds on Windows

This won't work on projects being built on Windows; I suspect you'll have to set up a hybrid shell-script and batch-file flow … or something like that.

(I ran into this issue a while back when trying to port some of my own work to build on Windows. I don't have a Windows machine handy to provide specific advice with, though.)

Write a <run script> verifyConditions plugin

Run any script. If the exit code is 0, then it's a "verified okay". Otherwise, don't publish.

Because it might be that the tests should pass, but the publish should not. (I have a specific use case in mind, but can't talk publically about it yet - client project).

Using this with an application instead of a module?

Hi!

First of all, I think this project is really cool, and I'd like to use it in my project.

Here's the trouble, my project (currently) is a web app (SPA, so the client and server are totally separate), and I'm having trouble figuring out how to use this project with that.

Mostly, I'm concerned about publishing to some server instead of NPM.

Is this possible?
Thanks, and sorry if this is the wrong place to ask.

feature request: support private npm packages

<3

Create a semantic-release-plugin yeoman generator.

With all the new plugins we're going to make, it makes sense to create a yeoman generator to remove some of the overhead.

Roadmap 4.x@latest

The 4.x rewrite is very stable in general, but I'd like to address a few more things before 4.x officially moves to latest.

• 700ec9d Implement plugin pipelines, so it's possible to run multiple verifications easily, w/o any overhead.
• Come up with a way to automatically do the right thing when a next release is done for the first time. Currently: just an error
• Implement #40 and #41
• Make integration tests work and automatically executed on Travis
• Develop some more plugins, more dogfooding before we lock the plugin api, also bigger ecosystem
• … ?

Feedback appreciated

@christophwitzko @gr2m

Skipping a deployment with the npm provider because this branch is not permitted

I'm trying to deploy https://github.com/gr2m/couchdb-view-tester, the build looks good, but doesn't get deployed: https://travis-ci.org/gr2m/couchdb-view-tester/builds/61492518

I don't get the error message. I've set master as branch in deploy.on.branch. Anything I'm missing?

Write an india verifyRelease plugin

india is a very nice module by @bcherny, that can detect breaking changes, by diffing your module's interface derived from JSDoc style code comments.

I'd love to see a semantic-release verifyRelease plugin (just like cracks), but I might not immediately have the time to do it myself.

If you want to give this a shot let me know in this issue and I'm happy to help wherever I can. You can reach me in the semantic-release gitter room, or on Twitter.

Can't publish with semantic-release (over existing module?)

I've got a package already that had some versions already in npm - I've since added semantic-release (though I think I might have cocked up the commit message format already, but I'm not convinced it's related).

But now when I run git publish, it really doesn't want to go up - and I'm not quite sure what to do (short of skipping the semantic-release part - which I'd rather not):

» npm publish

> [email protected] prepublish .
> semantic-release pre

This is a dry run
Determining new version
Publishing v0.3.0
npm ERR! addLocalDirectory Could not pack "." to "/Users/remy/.npm/bind.js/0.0.0-semantically-released/package.tgz"
npm ERR! addLocal Could not install .
npm ERR! [email protected] prepublish: `semantic-release pre`
npm ERR! Exit status 1
...

Add interactive set up for travis.yml

Similar to travis setup [component], it'd be nice if the travis.yml configuration could be scripted, perhaps part of semantic-release setup.

Support .gitlabels-style commit messages

This is a great idea.

So, in that vein, I want to make it work with the committing conventions I already use (I call them git labels.) How difficult would it to be to extend this with a parser for a format like the following:

(tag tag tag) This commit introduces a message. With labels.

(Where tag is usually something like new, fix, - (minor), or something else like that.)

A brief glance at your code looks like it's pretty tightly-coupled to the Angular's concept of a hard-coded type value, differentiated from anything else in the commit-message … whereas my style is a little more free-form. I'd like to define more nuanced heuristics for ‘this is breaking’ or ‘this is backwards-compatible’; is that in line with your project-goals?

semantic-release@next

While the core principles of this module are pretty solid there are a few things that currently make it awful to use or much rather setup (because one doesn't use it that much really).

Being part of the publish lifecycle

The original idea of integrating semantic-release into the npm lifecycle was that it's easy to setup, because for example on Travis there are ready made deploy plugins that run npm publish and so it's working out of the box.
There are two reasons why this wasn't a good idea.

1. Making an integration into prepublish and postpublish work requires a lot of hacking around edge-cases, up to the point that most of the code that's currently present is for these hacks.
2. The Travis deploy integration with npm is so bad, that we need to do it ourselves anyways. Namely auth, where it still uses the old base64 encoded username and password, but also one can't pass arguments to the publish command itself.

How it could be done instead:

Have both the pre and the post step like they're now (without all the hacks) and wrap them in another npm script like npm run semantic-release that does nothing more than semantic-release pre && npm publish && semantic-release post. That'd require a slightly different Travis setup, but that could be generated anyways. See next point.

A list of hacks that would go away:

1. Having a placeholder version in the package.json
2. npm publish-ception, where it runs npm publish inside npm prepublish. No more error, even though it's been successful.
3. Parsing npmArgv to check if it really runs inside prepublish rather than link, pack or install.

The setup is horrifying

The ideal would be one setup wizard where you enter nothing more than github username and password
and it works. Both npm and travis auth is taken from the environment, but you can still enter your passwords and usernames if you want to have separate tokens.

That could mainly be accomplished by building an .npmrc with the right auth token that's taken from a secure environment variable. Both GH_TOKEN and NPM_TOKEN should be encrypted using the Travis API for that, rather than putting it in the .travis.yml.

Bloat

I tried to keep the setup wizard basic, because all the packages would be installed every single time (parsing yml, interactivity etc). I'd like to have a semantic-release cli that can be as bloated as we want, because it simply installs a really lean core that's the only thing that packages actually depend upon and install.

Tests

Stop using sinopia, spin up a real registry and basically use the same testing setup the npm cli itself uses. Write unit tests.

---

I want to get these things done, before adding new features, because it will make the entire project so much more maintainable and fun to work with.

npm enterprise: workaround bug where registry returns "500 not found"

https://github.com/semantic-release/semantic-release/blob/next/src/lib/last-release.js#L13 needs to be
if (err && (err.statusCode === 404 || /not found/.test(err.message.toLowerCase()))) return cb(null, {});

That fixes it.

Cleanup .npmrc files before publish?

I see .npmrc files in the published packages, and now for the first time saw a Failed to replace env in config: ${NPM_TOKEN} error when testing a module. No idea where this comes from, but the .npmrc files are the only ones that contain that string.

My test script runs npm start in a node_modules folder, so maybe it's a change in npm?

To reproduce the issue, try

git clone [email protected]:eHealthAfrica/kazana.git
cd kazana
npm install
npm test

if the app won't start, check logs in node_modules/integration-test/log/app.log.

After removing node_modules/integration-test/.npmrc, things worked as expected

$ node -v && npm -v
v0.10.32
2.13.3

Any idea?

Empty value for parameter 'owner': undefined undefined

I've run into this before, and I think you said it happens randomly and it will be fixed with next semantic-release, but here it is for reference:
https://travis-ci.org/eHealthAfrica/joffrey-bootstrap/builds/71077848#L144

If, by chance, you know how to aovid / workaround / fix this, please enlighten me 💡

semantic-release always wants to publish v1.0.0

after successful publishing of v1.0.0 semantic-release stays at v1.0.0 even after two commits (refactor + feat).

a1feefe5f1a1a4b7ee25bc34bed4c9984fce0c48 -> v1.0.0 ok
73032331d9fcece165e10a1816fe3de93ab9cd0e -> v1.0.0 why?
61fa7cf86528e04f4c556b4f06e472770dbc1123 -> v1.0.0 why?

---- arlac77/uti changelog ---
commit 74a84ce4ec9351e00d40b1f0d2daef8bdd12e887
Author: Markus Felten [email protected]
Date: Sun Jun 21 13:45:16 2015 +0200

version=1.0.0 (maybe that helps semantic-release a bit)

commit 61fa7cf86528e04f4c556b4f06e472770dbc1123
Author: Markus Felten [email protected]
Date: Sun Jun 21 13:41:04 2015 +0200

refactor(initialize): removed one unnecessary Promise layer

commit 73032331d9fcece165e10a1816fe3de93ab9cd0e
Author: Markus Felten [email protected]
Date: Sun Jun 21 13:37:22 2015 +0200

feat: org.gnu.gnu-zip-tar-archive and public.zip-archive added to the predefined public UTIs

commit a1feefe5f1a1a4b7ee25bc34bed4c9984fce0c48
Author: Markus Felten [email protected]
Date: Sat Jun 20 16:44:38 2015 +0200

trying to fix travis deploy -> nvm

---