docs: made doc file org clearer and augmented content
This is a first step to improving the doc: - renamed directories; - augmented a fair bit of content. To be continued
This commit is contained in:
Emmanuel Sciara
committed by
Gregor Martynus
Gregor Martynus
parent
2d2bb38e61
commit
5a5eaec3da
@@ -1,5 +0,0 @@
|
||||
# Developer guide
|
||||
|
||||
- [JavaScript API](js-api.md)
|
||||
- [Plugins](plugin.md)
|
||||
- [Shareable configuration](shareable-configuration.md)
|
||||
@@ -1,270 +0,0 @@
|
||||
# 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 "${release.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<Result>
|
||||
|
||||
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`<br>
|
||||
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`<br>
|
||||
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)<br>
|
||||
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)<br>
|
||||
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`<br>
|
||||
|
||||
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<Object>`
|
||||
|
||||
The list of commit included in the new release.<br>
|
||||
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<Object>`
|
||||
|
||||
The list of releases published, one release per [publish plugin](../usage/plugins.md#publish-plugin).<br>
|
||||
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'
|
||||
}
|
||||
]
|
||||
```
|
||||
@@ -1,106 +0,0 @@
|
||||
# Plugin Developer Guide
|
||||
|
||||
To create a plugin for `semantic-release`, you need to decide which parts of the release lifecycle are important to that plugin. For example, it is best to always have a `verify` step because you may be receiving inputs from a user and want to make sure they exist. A plugin can abide by any of the following lifecycles:
|
||||
|
||||
- `verify`
|
||||
- `prepare`
|
||||
- `publish`
|
||||
- `success`
|
||||
- `fail`
|
||||
|
||||
`semantic-release` will require the plugin via `node` and look through the required object for methods named like the lifecyles stated above. For example, if your plugin only had a `verify` and `success` step, the `main` file for your object would need to `export` an object with `verify` and `success` functions.
|
||||
|
||||
In addition to the lifecycle methods, each lifecyle is passed two objects:
|
||||
|
||||
1. `pluginConfig` - an object containing the options that a user may pass in via their `release.config.js` file (or similar)
|
||||
2. `context` - provided by `semantic-release` for access to things like `env` variables set on the running process.
|
||||
|
||||
For each lifecycle you create, you will want to ensure it can accept `pluginConfig` and `context` as parameters.
|
||||
|
||||
## Creating a Plugin Project
|
||||
|
||||
It is recommended that you generate a new project with `yarn init`. This will provide you with a basic node project to get started with. From there, create an `index.js` file, and make sure it is specified as the `main` in the `package.json`. We will use this file to orchestrate the lifecycle methods later on.
|
||||
|
||||
Next, create a `src` or `lib` folder in the root of the project. This is where we will store our logic and code for how our lifecycle methods work. Finally, create a `test` folder so you can write tests related to your logic.
|
||||
|
||||
We recommend you setup a linting system to ensure good javascript practices are enforced. ESLint is usually the system of choice, and the configuration can be whatever you or your team fancies.
|
||||
|
||||
## Exposing Lifecycle Methods
|
||||
|
||||
In your `index.js` file, you can start by writing the following code
|
||||
|
||||
```javascript
|
||||
const verifyConditions = require('./src/verify');
|
||||
|
||||
let verified;
|
||||
|
||||
/**
|
||||
* Called by semantic-release during the verification step
|
||||
* @param {*} pluginConfig The semantic-release plugin config
|
||||
* @param {*} context The context provided by semantic-release
|
||||
*/
|
||||
async function verify(pluginConfig, context) {
|
||||
await verifyConditions(pluginConfig, context);
|
||||
verified = true;
|
||||
}
|
||||
|
||||
module.exports = { verify };
|
||||
```
|
||||
|
||||
Then, in your `src` folder, create a file called `verify.js` and add the following
|
||||
|
||||
```javascript
|
||||
const AggregateError = require('aggregate-error');
|
||||
|
||||
/**
|
||||
* A method to verify that the user has given us a slack webhook url to post to
|
||||
*/
|
||||
module.exports = async (pluginConfig, context) => {
|
||||
const { logger } = context;
|
||||
const errors = [];
|
||||
|
||||
// Throw any errors we accumulated during the validation
|
||||
if (errors.length > 0) {
|
||||
throw new AggregateError(errors);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
As of right now, this code won't do anything. However, if you were to run this plugin via `semantic-release`, it would run when the `verify` step occurred.
|
||||
|
||||
Following this structure, you can create different steps and checks to run through out the release process.
|
||||
|
||||
## Supporting Options
|
||||
|
||||
Let's say we want to verify that an `option` is passed. An `option` is a configuration object that is specific to your plugin. For example, the user may set an `option` in their release config like:
|
||||
|
||||
```js
|
||||
{
|
||||
prepare: {
|
||||
path: "@semantic-release/my-special-plugin"
|
||||
message: "My cool release message"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This `message` option will be passed to the `pluginConfig` object mentioned earlier. We can use the validation method we created to verify this option exists so we can perform logic based on that knowledge. In our `verify` file, we can add the following:
|
||||
|
||||
```js
|
||||
const { message } = pluginConfig;
|
||||
|
||||
if (message.length) {
|
||||
//...
|
||||
}
|
||||
```
|
||||
|
||||
## Supporting Environment Variables
|
||||
|
||||
Similar to `options`, environment variables exist to allow users to pass tokens and set special URLs. These are set on the `context` object instead of the `pluginConfig` object. Let's say we wanted to check for `GITHUB_TOKEN` in the environment because we want to post to GitHub on the user's behalf. To do this, we can add the following to our `verify` command:
|
||||
|
||||
```js
|
||||
const { env } = context;
|
||||
|
||||
if (env.GITHUB_TOKEN) {
|
||||
//...
|
||||
}
|
||||
```
|
||||
@@ -1 +0,0 @@
|
||||
# Shareable configuration developer guide
|
||||
Reference in New Issue
Block a user