Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(plugin developer guide): correction, additional details / advanced #1961

Merged
merged 1 commit into from
May 31, 2021
Merged

docs(plugin developer guide): correction, additional details / advanced #1961

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
38 changes: 35 additions & 3 deletions docs/developer-guide/plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,9 +183,14 @@ Compared to the verifyConditions, `analyzeCommits` lifecycle context has keys

Additional keys:

* `nextRelease`
* Similar object as `lastRelease` (see above)

* `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.
Expand Down Expand Up @@ -232,3 +237,30 @@ if (env.GITHUB_TOKEN) {
//...
}
```

## Execution order

For the lifecycles, the list at the top of the readme contains the order. If there are multiple plugins for the same lifecycle, then the order of the plugins determines the order in which they are executed.

## Handling errors

In order to be able to detect and handle errors properly, the errors thrown from the must be of type [SemanticReleaseError](https://github.com/semantic-release/error) or extend it as described in the package readme. This way the errors are handled properly and plugins using the `fail` lifecycle receive the errors correctly. For any other types of errors the internal error handling does nothing, lets them through up until the final catch and does not call any `fail` plugins.

## Advanced

Knowledge that might be useful for plugin developers.

### Multiple analyzeCommits plugins

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

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.