mirror of
https://github.com/cycjimmy/semantic-release-action.git
synced 2025-11-07 18:56:56 +00:00
Merge pull request #27 from cycjimmy/docs/optimizing-documents
Docs/optimizing documents
This commit is contained in:
Geoffrey.C
GitHub
commit
2f8514fa4d
2 changed files with 104 additions and 43 deletions
2
.github/workflows/testRelease.yml
vendored
2
.github/workflows/testRelease.yml
vendored
|
|
@ -70,7 +70,7 @@ jobs:
|
|||
|
||||
- name: Semantic Release
|
||||
uses: ./
|
||||
id: semantic_v15
|
||||
id: semantic
|
||||
with:
|
||||
semantic_version: 15
|
||||
dry_run: true
|
||||
|
|
|
|||
145
README.md
145
README.md
|
|
@ -1,39 +1,19 @@
|
|||
# Semantic Release Action
|
||||
![][workflows-badge-image]
|
||||
[![Release date][release-date-image]][release-url]
|
||||
[![semantic-release][semantic-image]][semantic-url]
|
||||
![npm license][license-image]
|
||||
|
||||
[workflows-badge-image]: https://github.com/cycjimmy/semantic-release-action/workflows/Test%20Release/badge.svg
|
||||
[semantic-url]: https://github.com/semantic-release/semantic-release
|
||||
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
||||
[license-image]: https://img.shields.io/npm/l/@cycjimmy/semantic-release-action.svg?style=flat-square
|
||||
[![npm license][license-image]][license-url]
|
||||
|
||||
GitHub Action for [Semantic Release](https://github.com/semantic-release/semantic-release).
|
||||
|
||||
## Usage
|
||||
#### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository.
|
||||
### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository.
|
||||
|
||||
#### Step2: [Add Secrets](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables.
|
||||
### Step2: [Add Secrets](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables.
|
||||
|
||||
#### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes.
|
||||
* inputs:
|
||||
* `semantic_version`: [Optional] Specify specifying version range for semantic-release. If no version range is specified, latest version will be used by default.
|
||||
* `branches`: [Optional] The branches on which releases should happen. It will override the branches attribute in your configuration file. If the attribute is not configured on both sides, the default is `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`. **Support for semantic-release above v16**. See https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches for more information.
|
||||
* `branch`: [Optional] The branch on which releases should happen. It will override the branch attribute in your configuration file. If the attribute is not configured on both sides, the default is master. **Support for semantic-release older than v16**.
|
||||
* `extra_plugins`: [Optional] Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer.
|
||||
* `dry_run`: [Optional] Whether to run semantic release in `dry-run` mode. It will override the dryRun attribute in your configuration file.
|
||||
* outputs:
|
||||
* `new_release_published`: Whether a new release was published. `true` or `false`
|
||||
* `new_release_version`: Version of the new release
|
||||
* `new_release_major_version`: Major version of the new release
|
||||
* `new_release_minor_version`: Minor version of the new release
|
||||
* `new_release_patch_version`: Patch version of the new release
|
||||
* `new_release_notes`: The release notes for the new release.
|
||||
|
||||
### Examples
|
||||
|
||||
#### A simple example
|
||||
### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes.
|
||||
|
||||
#### Basic Usage:
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
|
|
@ -45,8 +25,20 @@ steps:
|
|||
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
```
|
||||
|
||||
#### Setting `semantic_version` and `branch | branches` manually
|
||||
It is recommended to specify specifying version range for semantic-release. If no version range is specified, latest version will be used by default.
|
||||
**IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.
|
||||
If you are using this action for protected branches, replace `GITHUB_TOKEN` with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
|
||||
|
||||
### Inputs
|
||||
| Input Parameter | Required | Description |
|
||||
|:----------------:|:--------:|-------------|
|
||||
| semantic_version | false | [Details](#semantic_version) |
|
||||
| branches | false | [Details](#branches) |
|
||||
| branch | false | [Details](#branch) |
|
||||
| extra_plugins | false | [Details](#extra_plugins) |
|
||||
| dry_run | false | [Details](#dry_run) |
|
||||
|
||||
#### semantic_version
|
||||
> {Optional Input Parameter} Specify specifying version range for semantic-release. If no version range is specified, latest version will be used by default.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -57,12 +49,16 @@ steps:
|
|||
with:
|
||||
semantic_version: 15.13.28 # It is recommended to specify specifying version range
|
||||
# for semantic-release.
|
||||
branch: master # you can set branch for semantic-release older than v16.
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
```
|
||||
|
||||
*It is recommended to manually specify a version of semantic-release to prevent errors caused during the official semantic-release upgrade.*
|
||||
|
||||
#### branches
|
||||
> {Optional Input Parameter} The branches on which releases should happen. `branches` supports for **semantic-release above v16**.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
|
|
@ -92,11 +88,48 @@ steps:
|
|||
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
```
|
||||
|
||||
#### Passing Extra Plugins with `extra_plugins`
|
||||
`branches` will override the `branches` attribute in your configuration file. If the attribute is not configured on both sides, the default is:
|
||||
```
|
||||
[
|
||||
'+([0-9])?(.{+([0-9]),x}).x',
|
||||
'master',
|
||||
'next',
|
||||
'next-major',
|
||||
{name: 'beta', prerelease: true},
|
||||
{name: 'alpha', prerelease: true}
|
||||
]
|
||||
```
|
||||
|
||||
See [configuration#branches](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches) for more information.
|
||||
|
||||
#### branch
|
||||
> {Optional Input Parameter} Similar to parameter `branches`. The branch on which releases should happen. `branch` only supports for **semantic-release older than v16**.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v2
|
||||
- name: Semantic Release
|
||||
uses: cycjimmy/semantic-release-action@v2
|
||||
with:
|
||||
semantic_version: 15.13.28
|
||||
# you can set branch for semantic-release older than v16.
|
||||
branch: your-branch
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
```
|
||||
|
||||
It will override the `branch` attribute in your configuration file. If the attribute is not configured on both sides, the default is `master`.
|
||||
|
||||
#### extra_plugins
|
||||
> {Optional Input Parameter} Extra plugins for pre-install.
|
||||
|
||||
##### Passing Extra Plugins with `extra_plugins`:
|
||||
|
||||
The action can be used with `extra_plugins` option to specify plugins which are not in the [default list of plugins of semantic release](https://semantic-release.gitbook.io/semantic-release/usage/plugins#default-plugins). When using this option, please make sure that these plugins are also mentioned in your [semantic release config's plugins](https://semantic-release.gitbook.io/semantic-release/usage/configuration#plugins) array. For example, if you want to use `@semantic-release/git` and `@semantic-release/changelog` extra plugins, these must be added to `extra_plugins` in your actions file and `plugins` in your [release config file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) as shown bellow:
|
||||
|
||||
_github-action_
|
||||
##### Github Action Workflow:
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
|
|
@ -113,20 +146,19 @@ steps:
|
|||
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
```
|
||||
|
||||
_release-config_
|
||||
Similar to parameter `semantic_version`. *It is recommended to manually specify a version of semantic-release plugins to prevent errors caused.*
|
||||
|
||||
##### Release Config:
|
||||
```diff
|
||||
plugins: [
|
||||
.
|
||||
.
|
||||
+ "@semantic-release/changelog"
|
||||
+ "@semantic-release/git",
|
||||
]
|
||||
```
|
||||
|
||||
#### Manually Specify a Version of Semantic-release and Its Plugins
|
||||
|
||||
It is recommended to manually specify a version of semantic-release and its plugins to prevent errors caused during the official semantic-release upgrade.
|
||||
#### dry_run
|
||||
> {Optional Input Parameter} Whether to run semantic release in `dry-run` mode.<br> It will override the dryRun attribute in your configuration file.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -135,16 +167,23 @@ steps:
|
|||
- name: Semantic Release
|
||||
uses: cycjimmy/semantic-release-action@v2
|
||||
with:
|
||||
semantic_version: 15.14.0
|
||||
extra_plugins: |
|
||||
@semantic-release/git@7.0.18
|
||||
dry_run: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
```
|
||||
|
||||
#### Using Output Variables
|
||||
### Outputs
|
||||
| Output Parameter | Description |
|
||||
|:-------------------------:|---|
|
||||
| new_release_published | Whether a new release was published (`true` or `false`) |
|
||||
| new_release_version | Version of the new release. (e.g. `1.3.0`) |
|
||||
| new_release_major_version | Major version of the new release. (e.g. `1`) |
|
||||
| new_release_minor_version | Minor version of the new release. (e.g. `3`) |
|
||||
| new_release_patch_version | Patch version of the new release. (e.g. `0`) |
|
||||
| new_release_notes | The release notes for the new release. |
|
||||
|
||||
Using Output Variables:
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
|
|
@ -158,8 +197,30 @@ steps:
|
|||
|
||||
- name: Do something when a new release published
|
||||
if: steps.semantic.outputs.new_release_published == 'true'
|
||||
run: echo ${{ steps.semantic.outputs.new_release_version }}
|
||||
run: |
|
||||
echo ${{ steps.semantic.outputs.new_release_version }}
|
||||
echo ${{ steps.semantic.outputs.new_release_major_version }}
|
||||
echo ${{ steps.semantic.outputs.new_release_minor_version }}
|
||||
echo ${{ steps.semantic.outputs.new_release_patch_version }}
|
||||
```
|
||||
|
||||
## [CHANGELOG](./docs/CHANGELOG.md)
|
||||
## Changelog
|
||||
See [CHANGELOG.md][changelog-url].
|
||||
|
||||
## License
|
||||
This project are released under the [MIT License][license-url].
|
||||
|
||||
<!-- Links: -->
|
||||
[workflows-badge-image]: https://github.com/cycjimmy/semantic-release-action/workflows/Test%20Release/badge.svg
|
||||
|
||||
[release-date-image]: https://img.shields.io/github/release-date/cycjimmy/semantic-release-action
|
||||
[release-url]: https://github.com/cycjimmy/semantic-release-action/releases
|
||||
|
||||
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
||||
[semantic-url]: https://github.com/semantic-release/semantic-release
|
||||
|
||||
[license-image]: https://img.shields.io/npm/l/@cycjimmy/semantic-release-action.svg
|
||||
[license-url]: https://github.com/cycjimmy/semantic-release-action/blob/master/LICENSE
|
||||
|
||||
[changelog-url]: https://github.com/cycjimmy/semantic-release-action/blob/master/docs/CHANGELOG.md
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue