simon/semantic-release
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

style: prettier (#2624)

Browse Source
This commit is contained in:
Gregor Martynus
2022-11-23 16:02:51 -08:00
committed by GitHub
parent 8a0d8be51f
commit d13ea9280e
54 changed files with 3129 additions and 15324 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developer-guide/js-api.md
+46 -37
View File
@@ -3,43 +3,48 @@
## Usage
```js
const semanticRelease = require('semantic-release');
const {WritableStreamBuffer} = require('stream-buffers');
const semanticRelease = require("semantic-release");
const { WritableStreamBuffer } = require("stream-buffers");
const stdoutBuffer = WritableStreamBuffer();
const stderrBuffer = WritableStreamBuffer();
try {
const result = await semanticRelease({
// Core options
branches: [
'+([0-9])?(.{+([0-9]),x}).x',
'master',
'next',
'next-major',
{name: 'beta', prerelease: true},
{name: 'alpha', prerelease: true}
],
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
});
const result = await semanticRelease(
{
// Core options
branches: [
"+([0-9])?(.{+([0-9]),x}).x",
"master",
"next",
"next-major",
{ name: "beta", prerelease: true },
{ name: "alpha", prerelease: true },
],
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;
const { lastRelease, commits, nextRelease, releases } = result;
console.log(`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`);
console.log(
`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`
);
if (lastRelease.version) {
console.log(`The last release was "${lastRelease.version}".`);
@@ -49,14 +54,14 @@ try {
console.log(`The release was published with plugin "${release.pluginName}".`);
}
} else {
console.log('No release published.');
console.log("No release published.");
}
// Get stdout and stderr content
const logs = stdoutBuffer.getContentsAsString('utf8');
const errors = stderrBuffer.getContentsAsString('utf8');
const logs = stdoutBuffer.getContentsAsString("utf8");
const errors = stderrBuffer.getContentsAsString("utf8");
} catch (err) {
console.error('The automated release failed with %O', err)
console.error("The automated release failed with %O", err);
}
```
@@ -131,7 +136,7 @@ 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. |
@@ -140,6 +145,7 @@ Information related to the last release found:
**Notes**: If no previous release is found, `lastRelease` will be an empty `Object`.
Example:
```js
{
gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
@@ -157,7 +163,7 @@ 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. |
@@ -179,6 +185,7 @@ Each commit object has the following properties:
| committerDate | `String` | The committer date. |
Example:
```js
[
{
@@ -216,7 +223,7 @@ 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. |
@@ -225,6 +232,7 @@ Information related to the newly published release:
| channel | `String` | The distribution channel on which the next release will be made available (`undefined` for the default distribution channel). |
Example:
```js
{
type: 'minor',
@@ -244,7 +252,7 @@ The list of releases published or made available to a distribution channel.<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`). |
@@ -256,6 +264,7 @@ Each release object has the following properties:
| channel | `String` | The distribution channel on which the release is available (`undefined` for the default distribution channel). |
Example:
```js
[
{
docs/developer-guide/plugin.md
+97 -93
View File
@@ -34,7 +34,7 @@ We recommend you setup a linting system to ensure good javascript practices are
In your `index.js` file, you can start by writing the following code
```javascript
const verify = require('./src/verify');
const verify = require("./src/verify");
let verified;
@@ -54,7 +54,7 @@ module.exports = { verifyConditions };
Then, in your `src` folder, create a file called `verify.js` and add the following
```javascript
const AggregateError = require('aggregate-error');
const AggregateError = require("aggregate-error");
/**
* A method to verify that the user has given us a slack webhook url to post to
@@ -80,10 +80,10 @@ Let's say we want to verify that an `option` is passed. An `option` is a configu
```js
{
prepare: {
path: "@semantic-release/my-special-plugin"
message: "My cool release message"
}
prepare: {
path: "@semantic-release/my-special-plugin";
message: "My cool release message";
}
}
```
@@ -93,7 +93,7 @@ This `message` option will be passed to the `pluginConfig` object mentioned earl
const { message } = pluginConfig;
if (message.length) {
//...
//...
}
```
@@ -101,103 +101,104 @@ if (message.length) {
### Common context keys
* `stdout`
* `stderr`
* `logger`
- `stdout`
- `stderr`
- `logger`
### Context object keys by lifecycle
#### verifyConditions
Initially the context object contains the following keys (`verifyConditions` lifecycle):
* `cwd`
* Current working directory
* `env`
* Environment variables
* `envCi`
* Information about CI environment
* Contains (at least) the following keys:
* `isCi`
* Boolean, true if the environment is a CI environment
* `commit`
* Commit hash
* `branch`
* Current branch
* `options`
* Options passed to `semantic-release` via CLI, configuration files etc.
* `branch`
* Information on the current branch
* Object keys:
* `channel`
* `tags`
* `type`
* `name`
* `range`
* `accept`
* `main`
* `branches`
* Information on branches
* List of branch objects (see above)
- `cwd`
- Current working directory
- `env`
- Environment variables
- `envCi`
- Information about CI environment
- Contains (at least) the following keys:
- `isCi`
- Boolean, true if the environment is a CI environment
- `commit`
- Commit hash
- `branch`
- Current branch
- `options`
- Options passed to `semantic-release` via CLI, configuration files etc.
- `branch`
- Information on the current branch
- Object keys:
- `channel`
- `tags`
- `type`
- `name`
- `range`
- `accept`
- `main`
- `branches`
- Information on branches
- List of branch objects (see above)
#### analyzeCommits
Compared to the verifyConditions, `analyzeCommits` lifecycle context has keys
* `commits` (List)
* List of commits taken into account when determining the new version.
* Keys:
* `commit` (Object)
* Keys:
* `long` (String, Commit hash)
* `short` (String, Commit hash)
* `tree` (Object)
* Keys:
* `long` (String, Commit hash)
* `short` (String, Commit hash)
* `author` (Object)
* Keys:
* `name` (String)
* `email` (String)
* `date` (String, ISO 8601 timestamp)
* `committer` (Object)
* Keys:
* `name` (String)
* `email` (String)
* `date` (String, ISO 8601 timestamp)
* `subject` (String, Commit message subject)
* `body` (String, Commit message body)
* `hash` (String, Commit hash)
* `committerDate` (String, ISO 8601 timestamp)
* `message` (String)
* `gitTags` (String, List of git tags)
* `releases` (List)
* `lastRelease` (Object)
* Keys
* `version` (String)
* `gitTag` (String)
* `channels` (List)
* `gitHead` (String, Commit hash)
* `name` (String)
- `commits` (List)
- List of commits taken into account when determining the new version.
- Keys:
- `commit` (Object)
- Keys:
- `long` (String, Commit hash)
- `short` (String, Commit hash)
- `tree` (Object)
- Keys:
- `long` (String, Commit hash)
- `short` (String, Commit hash)
- `author` (Object)
- Keys:
- `name` (String)
- `email` (String)
- `date` (String, ISO 8601 timestamp)
- `committer` (Object)
- Keys:
- `name` (String)
- `email` (String)
- `date` (String, ISO 8601 timestamp)
- `subject` (String, Commit message subject)
- `body` (String, Commit message body)
- `hash` (String, Commit hash)
- `committerDate` (String, ISO 8601 timestamp)
- `message` (String)
- `gitTags` (String, List of git tags)
- `releases` (List)
- `lastRelease` (Object)
- Keys
- `version` (String)
- `gitTag` (String)
- `channels` (List)
- `gitHead` (String, Commit hash)
- `name` (String)
#### verifyRelease
Additional keys:
* `nextRelease` (Object)
* `type` (String)
* `channel` (String)
* `gitHead` (String, Git hash)
* `version` (String, version without `v`)
* `gitTag` (String, version with `v`)
* `name` (String)
- `nextRelease` (Object)
- `type` (String)
- `channel` (String)
- `gitHead` (String, Git hash)
- `version` (String, version without `v`)
- `gitTag` (String, version with `v`)
- `name` (String)
#### generateNotes
No new content in the context.
#### addChannel
*This is run only if there are releases that have been merged from a higher branch but not added on the channel of the current branch.*
_This is run only if there are releases that have been merged from a higher branch but not added on the channel of the current branch._
Context content is similar to lifecycle `verifyRelease`.
@@ -215,8 +216,8 @@ Lifecycles `success` and `fail` are mutually exclusive, only one of them will be
Additional keys:
* `releases`
* Populated by `publish` lifecycle
- `releases`
- Populated by `publish` lifecycle
#### fail
@@ -224,7 +225,7 @@ Lifecycles `success` and `fail` are mutually exclusive, only one of them will be
Additional keys:
* `errors`
- `errors`
### Supporting Environment Variables
@@ -237,13 +238,15 @@ if (env.GITHUB_TOKEN) {
//...
}
```
## Logger
Use `context.logger` to provide debug logging in the plugin.
```js
const { logger } = context;
logger.log('Some message from plugin.').
logger.log('Some message from plugin.').
```
The above usage yields the following where `PLUGIN_PACKAGE_NAME` is automatically inferred.
@@ -269,12 +272,13 @@ Knowledge that might be useful for plugin developers.
While it may be trivial that multiple analyzeCommits (or any lifecycle plugins) can be defined, it is not that self-evident that the plugins executed AFTER the first one (for example, the default one: `commit-analyzer`) can change the result. This way it is possible to create more advanced rules or situations, e.g. if none of the commits would result in new release, then a default can be defined.
The commit must be a known release type, for example the commit-analyzer has the following default types:
* major
* premajor
* minor
* preminor
* patch
* prepatch
* prerelease
- major
- premajor
- minor
- preminor
- patch
- prepatch
- prerelease
If the analyzeCommits-lifecycle plugin does not return anything, then the earlier result is used, but if it returns a supported string value, then that overrides the previous result.