Skip to content

Commit ed89361

Browse files
pvdlgpvdlg
committedJan 5, 2018
docs: documentation improvements
**Refactor and clarify the documentation in `README.md`** - Add Highlights - Add a Table of contents - Clarify the way semantic-release works - Clarify relationship with the CI environments - Describe local install for Node projects (with a `package.json`) and global install for non-JavaScript projects - Explain CI general configuration (environment variables and a run after all jobs are successful) - Clarify configuration (via config file or CLI arguments) - Clarify plugin roles and configuration - Add doc for shareable configuration - Add recipes - Add resources (Videos, articles, tutorials) - Add a Support section - Add a Team section **Add the following FAQs** - How can I use a npm build script that requires the `package.json`’s version ? - Can I use Semantic-release with Yarn? - Can I use Semantic-release to publish non-JavaScript packages? - Can I use Semantic-release with any CI service? - Can I use Semantic-release with any GitLab? - Can I use Semantic-release with any Git hosted environment? - Can I skip the release to the npm registry? - Can I use .npmrc options? - How can I set the access level of the published npm package? - Can I use Semantic-release to publish a package on Artifactory? - Can I set the initial release version of my package to 0.0.1? - Why does semantic-release require Node version >= 8? **Clarify Nove 8 requirement and solutions** - Add Node version requirement explanation and solutions - [X] Display a link to the documentation when running on Node < 8 version **Add recipes** - Travis - GitLab CI - Travis with build stages - To be done in #573 - CircleCI workflows - To be done in #573
·
v24.2.3v12.2.0
1 parent f4d9ebe commit ed89361

17 files changed

+841
-208
lines changed
 

Diff for: ‎README.md

+490-194
Large diffs are not rendered by default.

Diff for: ‎bin/semantic-release.js

+6-12
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,16 @@
33
// Bad news: We have to write plain ES5 in this file
44
// Good news: It's the only file of the entire project
55

6-
// eslint-disable-next-line no-var
6+
/* eslint-disable no-var */
7+
78
var semver = require('semver');
9+
var pkg = require('../package.json');
810

9-
if (semver.lt(process.version, '8.0.0')) {
11+
if (!semver.satisfies(process.version, pkg.engines.node)) {
1012
console.error(
11-
`semantic-release: node version >= 8 is required. Found ${process.version}.
12-
13-
If there is another job running on node version >= 8, it will be picked as
14-
the build leader and you can safely ignore this message.
15-
16-
If you don't have node 8 in your build matrix you can use "npx" to restore
17-
compatibility with minimal overhead:
18-
19-
$ npx -p node@8 npm run semantic-release
13+
`[semantic-release]: node version ${pkg.engines.node} is required. Found ${process.version}.
2014
21-
npx is bundled with npm >= 5.4, or available via npm. More info: npm.im/npx`
15+
See https://github.com/semantic-release/semantic-release/blob/caribou/docs/node-version.md for more details and solutions.`
2216
);
2317
process.exit(1);
2418
}

Diff for: ‎docs/README.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# semantic-release documentation
2+
3+
- [Plugins](plugins.md#semantic-release-plugins) - List of semantic-release plugins
4+
- [Shareable configurations](shareable-configurations.md#semantic-release-shareable-configurations) - List of semantic-release shareable configs
5+
- [Developer Guide](developer-guide/README.md#semantic-release-developer-guide) - The essentials of writing a semantic-release plugin or shareable config
6+
- [Recipes](recipes/README.md#semantic-release-recipes) - Community written recipes for common semantic-release use-cases
7+
- [Troubleshooting](troubleshooting.md#troubleshooting-semantic-release) - Community written troubleshooting guide to help with common semantic-release issues

Diff for: ‎docs/developer-guide/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# semantic-release Developer Guide

Diff for: ‎docs/developer-guide/plugin.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# semantic-release plugin development

Diff for: ‎docs/developer-guide/shareable-configuration.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# semantic-release shareable config development

Diff for: ‎docs/node-version.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Node version requirement
2+
3+
semantic-release is written using the latest [ECMAScript 2017](https://www.ecma-international.org/publications/standards/Ecma-262.htm) features, without transpilation which requires **requires Node version 8 or higher**.
4+
5+
semantic-release is meant to be used in a CI environment as a development support tool, not as a production dependency. Therefore the only constraint is to run the `semantic-release` in a CI environment providing Node 8 or higher.
6+
7+
See our [Node Support Policy](../README.md#node-support-policy) for our long-term promise regarding Node version support.
8+
9+
## Recommended solution
10+
11+
### Run at least one CI job with Node >= 8
12+
13+
The recommended approach is to run the `semantic-release` command from a CI job running on Node 8 or higher. This can either be a job used by your project to test on Node 8 or a dedicated job for the release steps.
14+
15+
See [CI configuration](../README.md#ci-configuration) and [CI configuration recipes](recipes/README.md#ci-configurations) for more details.
16+
17+
## Alternative solutions
18+
19+
### Use `npx`
20+
21+
[`npx`](https://github.com/zkat/npx) is a CLI to execute npm binaries. It is bundled with [npm](https://www.npmjs.com/package/npm) >= 5.4, or can be installed via `npm install -g npx`.
22+
23+
`npx` can be used to download the [Node 8 package published on npm](https://www.npmjs.com/package/node) and use it to execute the `semantic-release` command.
24+
25+
If you are using a [local](../README.md#local-installation) semantic-release installation:
26+
27+
```bash
28+
$ npm install -g npx && npx -p node@8 -c "npm run semantic-release"
29+
```
30+
31+
If you are using a [global](../README.md#global-installation) semantic-release installation:
32+
33+
```bash
34+
# For global semantic-release install
35+
$ npm install -g semantic-release npx && npx -p node@8 -c "semantic-release"
36+
```
37+
38+
### Use `nvm`
39+
40+
If your CI environment provides [nvm](https://github.com/creationix/nvm) you can use it to switch to Node 8 before running the `semantic-release` command.
41+
42+
If you are using a [local](../README.md#local-installation) semantic-release installation:
43+
44+
```bash
45+
$ nvm install 8 && npm run semantic-release
46+
```
47+
48+
If you are using a [global](../README.md#global-installation) semantic-release installation:
49+
50+
```bash
51+
$ nvm install 8 && npm install -g semantic-release && semantic-release
52+
```

Diff for: ‎docs/plugins.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# semantic-release plugins
2+
3+
## Default plugins
4+
5+
- [@semantic-release/github](https://github.com/semantic-release/github)
6+
- [verifyConditions](https://github.com/semantic-release/github#verifyconditions): Verify the presence and the validity of the GitHub authentication and release configuration
7+
- [publish](https://github.com/semantic-release/github#publish): Publish a [GitHub release](https://help.github.com/articles/about-releases)
8+
9+
- [@semantic-release/npm](https://github.com/semantic-release/npm)
10+
- [verifyConditions](https://github.com/semantic-release/npm#verifyconditions): Verify the presence and the validity of the npm authentication and release configuration
11+
- [getLastRelease](https://github.com/semantic-release/npm#getlastrelease): Determine the last release of the package on the npm registry
12+
- [publish](https://github.com/semantic-release/npm#publish): Publish the package on the npm registry
13+
14+
## Official plugins
15+
16+
- [@semantic-release/gitlab](https://github.com/semantic-release/gitlab)
17+
- [verifyConditions](https://github.com/semantic-release/gitlab#verifyconditions): Verify the presence and the validity of the GitLab authentication and release configuration
18+
- [publish](https://github.com/semantic-release/gitlab#publish): Publish a [GitLab release](https://docs.gitlab.com/ce/workflow/releases.html)
19+
20+
- [@semantic-release/git](https://github.com/semantic-release/git)
21+
- [verifyConditions](https://github.com/semantic-release/git#verifyconditions): Verify the presence and the validity of the Git authentication and release configuration
22+
- [getLastRelease](https://github.com/semantic-release/git#getlastrelease): Determine the last release via Git tags on the repository
23+
- [publish](https://github.com/semantic-release/git#publish): Push a release commit and tag, including configurable files
24+
25+
- [@semantic-release/changelog](https://github.com/semantic-release/changelog)
26+
- [verifyConditions](https://github.com/semantic-release/changelog#verifyconditions): Verify the presence and the validity of the configuration
27+
- [publish](https://github.com/semantic-release/changelog#publish): Create or update the changelog file in the local project repository
28+
29+
- [@semantic-release/exec](https://github.com/semantic-release/exec)
30+
- [verifyConditions](https://github.com/semantic-release/exec#verifyconditions): Execute a shell command to verify if the release should happen
31+
- [getLastRelease](https://github.com/semantic-release/exec#getlastrelease): Execute a shell command to determine the last release
32+
- [analyzeCommits](https://github.com/semantic-release/exec#analyzecommits): Execute a shell command to determine the type of release
33+
- [verifyRelease](https://github.com/semantic-release/exec#verifyrelease): Execute a shell command to verifying a release that was determined before and is about to be published.
34+
- [generateNotes](https://github.com/semantic-release/exec#analyzecommits): Execute a shell command to generate the release note
35+
- [publish](https://github.com/semantic-release/exec#publish): Execute a shell command to publish the release.
36+
37+
## Community plugins

Diff for: ‎docs/recipes/README.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# semantic-release recipes
2+
3+
## CI configurations
4+
- [CircleCI 2.0 workflows](circleci-workflows.md)
5+
- [Travis CI](travis.md)
6+
- [Travis CI with build stages](travis-build-stages.md)
7+
- [GitLab CI](gitlab-ci.md)
8+
9+
## Package managers and languages

Diff for: ‎docs/recipes/circleci-workflows.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# CircleCI 2.0 workflows

Diff for: ‎docs/recipes/gitlab-ci.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Using semantic-release with [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd)
2+
3+
## Environment variables
4+
5+
The [Authentication](../../README.md#authentication) environment variables can be configured with [Secret variables](https://docs.gitlab.com/ce/ci/variables/README.html#secret-variables).
6+
7+
## Node project configuration
8+
9+
GitLab CI supports [Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html) allowing to test on multiple Node versions and publishing a release only when all test pass.
10+
11+
**Note**: The publish pipeline must run a [Node >= 8 version](../../README.md#why-does-semantic-release-require-node-version--8).
12+
13+
### `.gitlab-ci.yml` configuration for Node projects
14+
15+
This example is a minimal configuration for semantic-release with a build running Node 4, 6 and 8 on Linux. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
16+
17+
**Note**: The`semantic-release` execution command varies depending if you are using a [local](../../README.md#local-installation) or [global](../../README.md#global-installation) semantic-release installation.
18+
19+
```yaml
20+
# The release pipeline will run only if all jobs in the test pipeline are successful
21+
stages:
22+
- test
23+
- release
24+
25+
before_script:
26+
- npm install
27+
28+
node:4:
29+
image: node:4
30+
stage: test
31+
script:
32+
- npm test
33+
34+
node:6:
35+
image: node:6
36+
stage: test
37+
script:
38+
- npm test
39+
40+
node:8:
41+
image: node:8
42+
stage: test
43+
script:
44+
- npm test
45+
46+
publish:
47+
image: node:8
48+
stage: release
49+
script:
50+
# Only for a local semantic-release installation
51+
- npm run semantic-release
52+
53+
# Only for a global semantic-release installation
54+
- npm install semantic-release
55+
- semantic-release
56+
```
57+
58+
### `package.json` configuration
59+
60+
A `package.json` is required only for [local semantic-release installations](../../README.md#local-installation).
61+
62+
```json
63+
{
64+
"devDependencies": {
65+
"semantic-release": "^12.0.0"
66+
},
67+
"scripts": {
68+
"semantic-release": "semantic-release"
69+
}
70+
}
71+
```

Diff for: ‎docs/recipes/travis-build-stages.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Using semantic-release with [Travis CI build stages](https://docs.travis-ci.com/user/build-stages)

Diff for: ‎docs/recipes/travis.md

+151
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Using semantic-release with [Travis CI](https://travis-ci.org)
2+
3+
## Environment variables
4+
5+
The [Authentication](../../README.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env).
6+
7+
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../README.md#automatic-setup-with-semantic-release-cli).
8+
9+
## Single Node job configuration
10+
11+
For projects that require to be tested only with a single [Node version](https://docs.travis-ci.com/user/getting-started/#Selecting-a-different-programming-language) on [one Operating System](https://docs.travis-ci.com/user/getting-started/#Selecting-infrastructure-(optional)).
12+
13+
**Note**: [Node 8 is the minimal version required](../../README.md#why-does-semantic-release-require-node-version--8).
14+
15+
### `.travis.yml` configuration for single Node job
16+
17+
This example is a minimal configuration for semantic-release with a build running Node 8 on Linux. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
18+
19+
It's recommended to run the `semantic-release` command in the [Travis `script` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error happen the build will fail and Travis will send a notification.
20+
21+
**Note**: The`semantic-release` execution command varies depending if you are using a [local](../../README.md#local-installation) or [global](../../README.md#global-installation) semantic-release installation.
22+
23+
```yaml
24+
language: node_js
25+
26+
node_js: 8
27+
28+
script:
29+
# Run tests
30+
- npm run test
31+
32+
# Only for a local semantic-release installation
33+
- npm run semantic-release
34+
35+
# Only for a global semantic-release installation
36+
- npm install -g semantic-release
37+
- semantic-release
38+
```
39+
40+
### `package.json` configuration for single Node job
41+
42+
A `package.json` is required only for [local semantic-release installations](../../README.md#local-installation).
43+
44+
```json
45+
{
46+
"devDependencies": {
47+
"semantic-release": "^11.0.0"
48+
},
49+
"scripts": {
50+
"semantic-release": "semantic-release"
51+
}
52+
}
53+
```
54+
55+
## Multiple Node jobs configuration
56+
57+
For projects that require to be tested with multiple [Node versions](https://docs.travis-ci.com/user/languages/javascript-with-nodejs/#Specifying-Node.js-versions) and/or on multiple [Operating Systems](https://docs.travis-ci.com/user/multi-os).
58+
59+
**Note**: At least one job must run a [Node >= 8 version](../../README.md#why-does-semantic-release-require-node-version--8).
60+
61+
### `.travis.yml` configuration for multiple Node jobs
62+
63+
This example is a minimal configuration for semantic-release with a build running Node 4, 6 and 8 on Linux and OSX. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
64+
65+
This example uses [`travis-deploy-once`](https://github.com/semantic-release/travis-deploy-once) in order to command [Run `semantic-release` only after all tests succeeded](../../README.md#run-semantic-release-only-after-all-tests-succeeded). Alternatively you can use [Travis CI Build Stages recipe](travis-build-stages.md).
66+
67+
It's recommended to run the `semantic-release` command in the [Travis `script` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error happen the build will fail and Travis will send a notification.
68+
69+
**Note**: The`semantic-release` execution command varies depending if you are using a [local](../../README.md#local-installation) or [global](../../README.md#global-installation) semantic-release installation.
70+
71+
```yaml
72+
language: node_js
73+
74+
node_js:
75+
- 8
76+
- 6
77+
- 4
78+
79+
os:
80+
- linux
81+
- osx
82+
83+
script:
84+
# Run tests
85+
- npm run test
86+
87+
# Only for a local semantic-release installation
88+
- npm run travis-deploy-once "npm run semantic-release"
89+
90+
# Only for a global semantic-release installation
91+
- npm install -g travis-deploy-once semantic-release
92+
- travis-deploy-once "semantic-release"
93+
```
94+
95+
**Note**: See the `travis-deploy-once` [`pro`](https://github.com/semantic-release/travis-deploy-once#-p---pro) and [`travis-url`](https://github.com/semantic-release/travis-deploy-once#-u---travis-url) options for using with [Travis Pro](https://docs.travis-ci.com/user/travis-pro) and [Travis Enterprise](https://enterprise.travis-ci.com).
96+
97+
### `package.json` configuration for multiple Node jobs
98+
99+
A `package.json` is required only for [local semantic-release installations](../../README.md#local-installation).
100+
101+
```json
102+
{
103+
"devDependencies": {
104+
"semantic-release": "^12.0.0",
105+
"travis-deploy-once": "^4.0.0"
106+
},
107+
"scripts": {
108+
"semantic-release": "semantic-release",
109+
"travis-deploy-once": "travis-deploy-once"
110+
}
111+
}
112+
```
113+
114+
## Non-JavaScript projects configuration
115+
116+
For projects that require to be tested with one or multiple version of a Non-JavaScript [language](https://docs.travis-ci.com/user/languages), optionally on multiple [Operating Systems](https://docs.travis-ci.com/user/multi-os).
117+
118+
This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../../README.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the semantic-release configuration.
119+
120+
### `.travis.yml` configuration for non-JavaScript projects
121+
122+
This example is a minimal configuration for semantic-release with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go) on Linux and OSX. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
123+
124+
This example uses [`travis-deploy-once`](https://github.com/semantic-release/travis-deploy-once) in order to [run `semantic-release` only after all tests succeeded](../../README.md#run-semantic-release-only-after-all-tests-succeeded). Alternatively you can use [Travis CI Build Stages recipe](travis-build-stages.md).
125+
126+
It's recommended to run the `semantic-release` command in the [Travis `script` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error happen the build will fail and Travis will send a notification.
127+
128+
```yaml
129+
language: go
130+
131+
go:
132+
- 1.6
133+
- 1.7
134+
135+
os:
136+
- linux
137+
- osx
138+
139+
script:
140+
# Run tests
141+
- go test -v ./...
142+
143+
# Use nvm to install and use the Node LTS version (nvm is installed on Travis images)
144+
- nvm install lts/*
145+
# Install travis-deploy-once and semantic-release
146+
- npm install -g travis-deploy-once semantic-release
147+
# Run semantic-release only on job, after all other are successful
148+
- travis-deploy-once "semantic-release"
149+
```
150+
151+
**Note**: See the `travis-deploy-once` [`pro`](https://github.com/semantic-release/travis-deploy-once#-p---pro) and [`travis-url`](https://github.com/semantic-release/travis-deploy-once#-u---travis-url) options for using with [Travis Pro](https://docs.travis-ci.com/user/travis-pro) and [Travis Enterprise](https://enterprise.travis-ci.com).

Diff for: ‎docs/shareable-configurations.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# semantic-release shareable configurations
2+
3+
## Official configurations
4+
- [@semantic-release/apm-config](https://github.com/semantic-release/apm-config) - :atom: semantic-release shareable config for releasing atom packages
5+
- [@semantic-release/gitlab-config](https://github.com/semantic-release/gitlab-config) - :fox_face: semantic-release shareable config for GitLab
6+
7+
## Community configurations

Diff for: ‎TROUBLESHOOTING.md renamed to ‎docs/troubleshooting.md

File renamed without changes.

Diff for: ‎media/semantic-release-cli.png

117 KB
Loading

Diff for: ‎package.json

+6-2
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@
1414
"path": "cz-conventional-changelog"
1515
}
1616
},
17+
"contributors": [
18+
"Gregor Martynus (https://twitter.com/gr2m)",
19+
"Pierre Vanduynslager (https://twitter.com/@pvdlg_)"
20+
],
1721
"dependencies": {
1822
"@semantic-release/commit-analyzer": "^5.0.0",
1923
"@semantic-release/error": "^2.1.0",
@@ -60,11 +64,11 @@
6064
"xo": "^0.18.2"
6165
},
6266
"engines": {
63-
"node": ">=4",
64-
"npm": ">=2"
67+
"node": ">=8"
6568
},
6669
"files": [
6770
"bin",
71+
"docs",
6872
"lib",
6973
"index.js",
7074
"cli.js"

0 commit comments

Comments
 (0)
Please sign in to comment.