Skip to content

Latest commit

 

History

History
201 lines (122 loc) · 13.7 KB

FAQ.md

File metadata and controls

201 lines (122 loc) · 13.7 KB
Raw

Frequently Asked Questions

Why is the package.json’s version not updated in my repository?

semantic-release takes care of updating the package.json’s version before publishing to npm.

By default, only the published package will contains the version, which is the only place where it is really required, but the updated package.json will not be pushed to the Git repository

However, the @semantic-release/git plugin can be used to push the updated package.json as well as other files to the Git repository.

How can I use a npm build script that requires the package.json’s version ?

The package.json’s version will be updated by the semantic-release command just before publishing to npm, therefore it won't be available for scripts ran before the semantic-release command.

As semantic-release uses the npm CLI to publish, all npm hook scripts will be executed. Therefore you can run your build script in the prepublishOnly hook. It will be executed after the semantic-release command update the package.json’s version and before publishing.

Is there a way to preview which version would currently get published?

Yes with the dry-run options which prints to the console the next version to be published and the release notes.

Can I use semantic-release with Yarn?

If you are using a local semantic-release installation and run multiple CI jobs with different versions, the yarn install command will fail on jobs running with Node < 8 as semantic-release requires Node >= 8.3 and specifies it in its package.jsons engines key.

The recommended solution is to use the Yarn --ignore-engines option to install the project dependencies on the CI environment, so Yarn will ignore the semantic-release's engines key:

$ yarn install --ignore-engines

Note: Several CI services use Yarn by default if your repository contains a yarn.lock file. So you should override the install step to specify yarn install --ignore-engines.

Alternatively you can use a global semantic-release installation and make sure to install and run the semantic-release command only in a CI jobs running with Node >= 8.3.

If your CI environment provides nvm you can switch to Node 8 before installing and running the semantic-release command:

$ nvm install 8 && yarn global add semantic-release && semantic-release

See the CI configuration recipes for more details on specific CI environments.

As semantic-release is recommended to be executed with npx an alternative is required for usage with Yarn. Even though it is possible to install npx with Yarn, it's not recommended. Yarn and npx would be using different cache locations.

For local installation replace npx semantic-release with yarn run semantic-release.

For global installation replace npx semantic-release with yarn global add semantic-release && semantic-release.

Can I use semantic-release to publish non-JavaScript packages?

Yes, semantic-release is a Node CLI application but it can be used to publish any type of packages.

To publish a non-Node package (without a package.json) you would need to:

See the CI configuration recipes for more details on specific CI environments.

In addition you will need to configure the semantic-release plugins to:

Here is a basic example to create GitHub releases and use shell command to publish:

{
  "verifyConditions": ["@semantic-release/github"],
  "prepare": [
    {
      "path": "@semantic-release/exec",
      "cmd": "set-version ${nextRelease.version}"
    }
  ],
  "publish": [
    "@semantic-release/github",
    {
      "path": "@semantic-release/exec",
      "cmd": "publish-package"
    }
  ],
}

Note: This is a theoretical example where the command set-version update the project version with the value passed as its first argument and publish-package publishes the package to a registry.

See the package managers and languages recipes for more details on specific project types.

Can I use semantic-release with any CI service?

Yes, semantic-release can be used with any CI service, as long as it provides:

See the CI configuration recipes for more details on specific CI environments.

Can I run semantic-release on my local machine rather than on a CI server?

Yes, you can by explicitly setting the --no-ci CLI option option. You will also have to set the required authentication via environment variables on your local machine, for example:

$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci

However this is not the recommended approach, as running unit and integration tests on an independent machine before publishing software is a crucial part of the release workflow.

Can I use semantic-release with GitLab?

Yes, with the @semantic-release/gitlab-config shareable configuration.

See the GitLab CI recipes for the CI configuration.

Can I use semantic-release with any Git hosted environment?

By default semantic-release uses the @semantic-release/github plugin to publish a GitHub release. For other Git hosted environment the @semantic-release/git and @semantic-release/changelog plugins can be used via plugins configuration.

See the @semantic-release/git @semantic-release/changelog plugins documentation for more details.

Can I skip the release to the npm registry?

Yes, the publishing to the npm registry can be disabled with the npmPublish option of the @semantic-release/npm plugin. In addition the tarballDir option allow to generate the package tarball in order to publish it to your repository with the @semantic-release/git or to a GitHub release with the @semantic-release/github plugin.

See the @semantic-release/npm plugin documentation for more details.

Can I use .npmrc options?

Yes, all the npm configuration options are supported via the .npmrc file at the root of your repository.

See the @semantic-release/npm plugin documentation for more details.

How can I set the access level of the published npm package?

The npm access option can be set in the .npmrc file at the root of your repository:

access=public

Or with the publishConfig.access key in your project's package.json:

{
  "publishConfig": {
    "access": "public"
  }
}

Can I use semantic-release to publish a package on Artifactory?

Any npm compatible registry is supported with the @semantic-release/npm plugin. For Artifactory versions prior to 5.4, the legacy authentication has to be used (with NPM_USERNAME, NPM_PASSWORD and NPM_EMAIL environment variables).

See npm registry authentication for more details.

See Artifactory - npm Registry documentation for Artifactiry configuration.

Can I manually trigger the release of a specific version?

You can trigger a release by pushing to your Git repository. You deliberately cannot trigger a specific version release, because this is the whole point of semantic-release.

Can I exclude commits from the analysis?

Yes, every commits that contains [skip release] or [release skip] in their message will be excluded from the commit analysis and won't participate in the release type determination.

Is it really a good idea to release on every push?

It is indeed a great idea because it forces you to follow best practices. If you don’t feel comfortable releasing every feature or fix on your master you might not treat your master branch as intended.

From Understanding the GitHub Flow:

Branching is a core concept in Git, and the entire GitHub Flow is based upon it. There's only one rule: anything in the master branch is always deployable.

If you need more control over the timing of releases, see Triggering a release for different options.

Can I set the initial release version of my package to 0.0.1?

This is not supported by semantic-release as it's not considered a good practice, mostly because Semantic Versioning rules applies differently to major version zero.

In early development phase when your package is not ready for production yet we recommend to publish releases on a distribution channel (for example npm’s dist-tags) or to develop on a dev branch and merge it to master periodically. See Triggering a release for more details on those solutions.

See “Introduction to SemVer” - Irina Gebauer for more details on Semantic Versioning and the recommendation to start at version 1.0.0.

Can I trust semantic-release with my releases?

semantic-release has a full unit and integration test suite that tests npm publishes against the npm-registry-couchapp.

In addition the verify conditions step verifies that all necessary conditions for proceeding with a release are met, and a new release will be performed only if all your tests pass.

Why does semantic-release require Node version >= 8.3?

semantic-release is written using the latest ECMAScript 2017 features, without transpilation which requires Node version 8.3 or higher.

See Node version requirement for more details and solutions.

What is npx?

npx – short for "npm exec" – is a CLI to find and execute npm binaries within the local node_modules folder or in the $PATH. If a binary can't be located npx will download the required package and execute it from its cache location. The tool is bundled with npm >= 5.2, or can be installed via npm install -g npx. For more details and motivation read the introductory blog post by @zkat.