diff --git a/README.md b/README.md index a677ba98..ffb58c30 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,7 @@ After running the tests the command `semantic-release` will execute the followin - [CI configurations](docs/recipes/README.md) - [Package managers and languages](docs/recipes/README.md) - Developer guide + - [JavaScript API](docs/developer-guide/js-api.md) - [Plugins](docs/developer-guide/plugin.md) - [Shareable configuration](docs/developer-guide/shareable-configuration.md) - Support diff --git a/SUMMARY.md b/SUMMARY.md index 56b12f13..a9cfa57d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -22,6 +22,7 @@ - [Package managers and languages](docs/recipes/README.md) ## Developer guide +- [JavaScript API](docs/developer-guide/js-api.md) - [Plugin](docs/developer-guide/plugin.md) - [Shareable configuration](docs/developer-guide/shareable-configuration.md) diff --git a/docs/developer-guide/README.md b/docs/developer-guide/README.md index afd97c5d..e9b3d062 100644 --- a/docs/developer-guide/README.md +++ b/docs/developer-guide/README.md @@ -1,4 +1,5 @@ # Developer guide +- [JavaScript API](js-api.md) - [Plugins](plugin.md) - [Shareable configuration](shareable-configuration.md) diff --git a/docs/developer-guide/js-api.md b/docs/developer-guide/js-api.md new file mode 100644 index 00000000..415bf0ee --- /dev/null +++ b/docs/developer-guide/js-api.md @@ -0,0 +1,270 @@ +# JavaScript API + +## Usage + +```js +const semanticRelease = require('semantic-release'); +const {WritableStreamBuffer} = require('stream-buffers'); + +const stdoutBuffer = WritableStreamBuffer(); +const stderrBuffer = WritableStreamBuffer(); + +try { + const result = await semanticRelease({ + // Core options + branch: 'master', + repositoryUrl: 'https://github.com/me/my-package.git', + // Shareable config + extends: 'my-shareable-config', + // Plugin options + githubUrl: 'https://my-ghe.com', + githubApiPathPrefix: '/api-prefix' + }, { + // Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()` + cwd: '/path/to/git/repo/root', + // Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env` + env: {...process.env, MY_ENV_VAR: 'MY_ENV_VAR_VALUE'}, + // Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr` + stdout: stdoutBuffer, + stderr: stderrBuffer + }); + + if (result) { + const {lastRelease, commits, nextRelease, releases} = result; + + console.log(`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`); + + if (lastRelease.version) { + console.log(`The last release was "${lastRelease.version}".`); + } + + for (const release of releases) { + console.log(`The release was published with plugin "${pluginName}".`); + } + } else { + console.log('No release published.'); + } + + // Get stdout and stderr content + const logs = stdoutBuffer.getContentsAsString('utf8'); + const errors = stderrBuffer.getContentsAsString('utf8'); +} catch (err) { + console.error('The automated release failed with %O', err) +} +``` + +## API + +### semanticRelease([options], [config]) => Promise + +Run **semantic-release** and returns a `Promise` that resolves to a [Result](#result) object. + +#### options + +Type: `Object` + +**semantic-release** options. + +Can be used to set any [core option](../usage/configuration.md#configuration) or [plugin options](../usage/plugins.md#configuration). + +Each option, will take precedence over options configured in the [configuration file](../usage/configuration.md#configuration) and [shareable configurations](../usage/configuration.md#extends). + +#### config + +Type: `Object` + +**semantic-release** configuration specific for API usage. + +##### cwd + +Type: `String`
+Default: `process.cwd()` + +The current working directory to use. It should be configured to the root of the Git repository to release from. + +It allows to run **semantic-release** from a specific path without having to change the local process `cwd` with `process.chdir()`. + +##### env + +Type: `Object`
+Default: `process.env` + +The environment variables to use. + +It allows to run **semantic-release** with specific environment variables without having to modify the local `process.env`. + +##### stdout + +Type: [`stream.Writable`](https://nodejs.org/api/stream.html#stream_writable_streams)
+Default: `process.stdout` + +The [writable stream](https://nodejs.org/api/stream.html#stream_writable_streams) used to log information. + +It allows to configure **semantic-release** to write logs to a specific stream rather than the local `process.stdout`. + +##### stderr + +Type: [`stream.Writable`](https://nodejs.org/api/stream.html#stream_writable_streams)
+Default: `process.stderr` + +The [writable stream](https://nodejs.org/api/stream.html#stream_writable_streams) used to log errors. + +It allows to configure **semantic-release** to write errors to a specific stream rather than the local `process.stderr`. + +### Result + +Type: `Object` `Boolean`
+ +And object with [`lastRelease`](#lastrelease), [`nextRelease`](#nextrelease), [`commits`](#commits) and [`releases`](#releases) if a release is published or `false` if no release was published. + +#### lastRelease + +Type: `Object` + +Information related to the last release found: + +| Name | Type | Description | +|---------|----------|----------------------------------------------------------------------------------------------------| +| version | `String` | The version of the last release. | +| gitHead | `String` | The sha of the last commit being part of the last release. | +| gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the last release. | + +**Notes**: If no previous release is found, `lastRelease` will be an empty `Object`. + +Example: +```js +{ + gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709', + version: '1.0.0', + gitTag: 'v1.0.0', +} +``` + +#### commits + +Type: `Array` + +The list of commit included in the new release.
+Each commit object has the following properties: + +| Name | Type | Description | +|-----------------|----------|-------------------------------------------------| +| commit | `Object` | The commit abbreviated and full hash. | +| commit.long | `String` | The commit hash. | +| commit.short | `String` | The commit abbreviated hash. | +| tree | `Object` | The commit abbreviated and full tree hash. | +| tree.long | `String` | The commit tree hash. | +| tree.short | `String` | The commit abbreviated tree hash. | +| author | `Object` | The commit author information. | +| author.name | `String` | The commit author name. | +| author.email | `String` | The commit author email. | +| author.short | `String` | The commit author date. | +| committer | `Object` | The committer information. | +| committer.name | `String` | The committer name. | +| committer.email | `String` | The committer email. | +| committer.short | `String` | The committer date. | +| subject | `String` | The commit subject. | +| body | `String` | The commit body. | +| message | `String` | The commit full message (`subject` and `body`). | +| hash | `String` | The commit hash. | +| committerDate | `String` | The committer date. | + +Example: +```js +[ + { + commit: { + long: '68eb2c4d778050b0701136ca129f837d7ed494d2', + short: '68eb2c4' + }, + tree: { + long: '7ab515d12bd2cf431745511ac4ee13fed15ab578', + short: '7ab515d' + }, + author: { + name: 'Me', + email: 'me@email.com', + date: 2018-07-22T20:52:44.000Z + }, + committer: { + name: 'Me', + email: 'me@email.com', + date: 2018-07-22T20:52:44.000Z + }, + subject: 'feat: a new feature', + body: 'Description of the new feature', + hash: '68eb2c4d778050b0701136ca129f837d7ed494d2', + message: 'feat: a new feature\n\nDescription of the new feature', + committerDate: 2018-07-22T20:52:44.000Z + } + ] +``` + +#### nextRelease + +Type: `Object` + +Information related to the newly published release: + +| Name | Type | Description | +|---------|----------|---------------------------------------------------------------------------------------------------| +| type | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`). | +| version | `String` | The version of the new release. | +| gitHead | `String` | The sha of the last commit being part of the new release. | +| gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the new release. | +| notes | `String` | The release notes for the new release. | + +Example: +```js +{ + type: 'minor', + gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2', + version: '1.1.0', + gitTag: 'v1.1.0', + notes: 'Release notes for version 1.1.0...', +} +``` + +#### releases + +Type: `Array` + +The list of releases published, one release per [publish plugin](../usage/plugins.md#publish-plugin).
+Each release object has the following properties: + +| Name | Type | Description | +|------------|----------|-----------------------------------------------------------------------------------------------| +| name | `String` | **Optional.** The release name, only if set by the corresponding `publish` plugin. | +| url | `String` | **Optional.** The release URL, only if set by the corresponding `publish` plugin. | +| type | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`). | +| version | `String` | The version of the release. | +| gitHead | `String` | The sha of the last commit being part of the release. | +| gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the release. | +| notes | `String` | The release notes for the release. | +| pluginName | `String` | The name of the plugin that published the release. | + +Example: +```js +[ + { + name: 'GitHub release', + url: 'https://github.com/me/my-package/releases/tag/v1.1.0', + type: 'minor', + gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2', + version: '1.1.0', + gitTag: 'v1.1.0', + notes: 'Release notes for version 1.1.0...', + pluginName: '@semantic-release/github' + }, + { + name: 'npm package (@latest dist-tag)', + url: 'https://www.npmjs.com/package/my-package', + type: 'minor', + gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2', + version: '1.1.0', + gitTag: 'v1.1.0', + notes: 'Release notes for version 1.1.0...', + pluginName: '@semantic-release/npm' + } + ] +```