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

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

Browse Source 
A correction to the earlier documentation: the "nextRelease" object is NOT similar to the
lastRelease and there are some differences. Because of this, the object is now documented as a
separate entry. Added also information on how the error handling should be done so that
semantic-release would be able to handle errors from plugins properly and call "fail" lifecycle
plugins. Included some more advanced information on how the analyzeCommits-lifecycle plugins work
and how the result of the initial analyzer can be overridden. This is an edge case, but could happen
and is good to understand.
This commit is contained in:
Aki Mäkinen 2021-05-31 20:15:47 +03:00 committed by GitHub
parent 3edc917c7c
commit fe0ac417cf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 35 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/developer-guide/plugin.md
View File

@ -183,8 +183,13 @@ 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
@ -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.