General Release
Automatic Release Tool for Git repository using bash shell
Features
- Release version
- Analyze the release/pre-release version from the commits after the last git-tag
- Specifies the release/pre-release version number
- Increment the release/pre-release version at the specified level based on the last git-tag
- Generate release note
- Generate the release note from the commits after the last git-tag
- Generate changelog
- Git commit, tag, push
- CI support
- Appveyor
- Travis
- CircleCI
- GitlabCI
- Jenkins
- Archive files (use gzip plugin)
- Create release at GitHub (use github plugin)
- Create release at NPM (use npm plugin)
- Create release at Yum (use yum plugin)
- Create release at Maven (use maven plugin)
- Update appveyor build details (use appveyor plugin)
- Custom plugin
- Validate the commit message
- Tools: commit template and commit linter
Dependencies
- Bash Shell
- Git (
>=1.17.0
)
Commit Message Format
Each commit message consists of one or more headers and bodies. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject><body> <type>(<scope>): <subject><body>
The header is mandatory and the scope of the header is optional.
Release Rule Configuration (yml)
- The Config Fields
Field Name | Field Type | Description |
---|---|---|
tag_repo |
string | Git repository URL, default: [auto] Get the url with command: git config --get remote.origin.url |
tag_prefix |
string | Prefix of the Git tag , default: v |
release_note |
string | Release Note, default: [auto] Analyze the commits after the last Git tag by the rules defined in the configuration |
changelog |
string | Generante the changelog file, default: CHANGELOG.md |
commit |
string[] | Git commit files, default: CHANGELOG.md |
commit_message |
string | Commit message template, default: chore(release): {tag} [skip ci] , the format variables: - version : Release version - channel : Release channel - prerelease : Pre-release id - tag : Release Git tag |
commit_note |
boolean | Commit with release note, default: true |
plugins |
string[] | Plugins - github [--file, --token] [options] - npm [--registry, --access, --token] [options] - appveyor [options] - constum.sh [options] |
branchs | object[] | The branch config |
branchs[].pattern |
regexp | required : Pattern of the release branch name |
branchs[].channel |
string | Publish channel |
branchs[].prerelease |
string | Pre-release id |
rules | object[] | Rules for release version analyzer and release note generator |
rules[].type |
regexp | required : Pattern of the commit type |
rules[].scope |
regexp | Pattern of the commit scope |
rules[].release |
string | The Release type:major , minor , patch , none , default none |
rules[].prerelease |
string | The Pre-release type: major , minor , patch , prerelease , none , default: prerelease |
rules[].note |
string | Title of the release note |
rules[].body |
boolean | Include the commit body to release note |
- general-release looks the config file at
.release.yml
- Use
--config
or-c
to use another path - The default configuration: release.yml
Usage
Shell
-
Download general-release
# downloadcurl -L -s https://github.com/billowz/general-release/releases/download/$(curl -L -s -H 'Accept: application/json' https://github.com/billowz/general-release/releases/latest | sed -e 's/.*"tag_name":"\([^"]*\)".*/\1/')/general-release.zip -o general-release.zipunzip -o general-release.zip -d general-releaserm -f general-release.zip -
Release
# deploy with github plugingeneral-release/bin/bin.sh -c .release.yml -p "github -f release.zip" --debug# orgeneral-release/bin/bin.sh deploy -c .release.yml -p "github -f release.zip" --debug# dry-run modegeneral-release/bin/bin.sh -c .release.yml -p "github -f release.zip" --debug --dry-run -
Preview Release
general-release/bin/bin.sh preview -c .release.yml --debug# orgeneral-release/bin/bin.sh --no-deploy -c .release.yml --debug -
Release with the specialed version
# release with specified version: 1.0.0general-release/bin/bin.sh -v 1.0.0# release with specified version on the specified channelgeneral-release/bin/bin.sh -v 1.0.0@next# release with specified pre-release versiongeneral-release/bin/bin.sh -v 1.0.0-alpha# release with specified pre-release version on the specified channelgeneral-release/bin/bin.sh -v 1.0.0-alpha@next# increment the version by the specified level from the last git-taggeneral-release/bin/bin.sh -v minor# increment the version by the specified level on the specified channel from the last git-taggeneral-release/bin/bin.sh -v minor@next# increment the pre-release version by the specified level from the last git-taggeneral-release/bin/bin.sh -v pre-alpha# increment the pre-release version by the specified level on the specified channel from the last git-taggeneral-release/bin/bin.sh -v pre-alpha@next -
Validate the commit message
general-release/bin/bin.sh validate -c .release.yml "feat: test" -
Install the Tools: commit-linter, commit-template
# install commit template and commit lintergeneral-release/bin/bin.sh install -c .release.yml# ofgeneral-release/bin/bin.sh install -c .release.yml --commit-lint --commit-template# install commit templategeneral-release/bin/bin.sh install -c .release.yml --commit-template# install commit template on the specified filegeneral-release/bin/bin.sh install -c .release.yml --template ./commit-template -
Uninstall the Tools: commit-linter, commit-template
# uninstall commit template and commit lintergeneral-release/bin/bin.sh uninstall# ofgeneral-release/bin/bin.sh uninstall --commit-lint --commit-template# uninstall commit templategeneral-release/bin/bin.sh uninstall --commit-template -
Print Usage
general-release/bin/bin.sh -hgeneral-release/bin/bin.sh deploy -hgeneral-release/bin/bin.sh preview -hgeneral-release/bin/bin.sh validate -hgeneral-release/bin/bin.sh install -hgeneral-release/bin/bin.sh uninstall -h
NodeJS
- Set the default options in package.json with
releaseConfig
property
Property | Property Type | Description |
---|---|---|
releaseConfig.config |
string | The config file, default: .release.yml or node_modules/general-release/src/release.yml |
releaseConfig.commitTemplate |
string | The path of generated commit template file, default: .gitmessage |
releaseConfig.tools |
boolean, string, string[] | Auto install/uninstall the tools: commit-template , commit-lint , default: true - true : Install/Uninstall all tools on install/uninstall general-release - false : Not install/uninstall any tools on install/uninstall general-release - string , string[] : Install/Uninstall the specified tools on install/uninstall general-release |
- e.g.
-
Install general-release
npm install -g general-release# ornpm install -D general-release -
Release
# deploy with github and npm pluginnpx general-release -c .release.yml -p "github -f release.zip" -p npm --debug# ornpx general-release deploy -c .release.yml -p "github -f release.zip" -p npm --debug# dry-run modenpx general-release -c .release.yml -p "github -f release.zip" -p npm --debug --dry-run -
Preview Release
npx general-release preview -c .release.yml --debug# ornpx general-release --no-deploy -c .release.yml --debug -
Release with the specialed version
# release with specified version: 1.0.0npx general-release -v 1.0.0# release with specified version on the specified channelnpx general-release -v 1.0.0@next# release with specified pre-release versionnpx general-release -v 1.0.0-alpha# release with specified pre-release version on the specified channelnpx general-release -v 1.0.0-alpha@next# increment the version by the specified level from the last git-tagnpx general-release -v minor# increment the version by the specified level on the specified channel from the last git-tagnpx general-release -v minor@next# increment the pre-release version by the specified level from the last git-tagnpx general-release -v pre-alpha# increment the pre-release version by the specified level on the specified channel from the last git-tagnpx general-release -v pre-alpha@next -
Validate the commit message
npx general-release validate -c .release.yml "feat: test" -
Install the Tools: commit-linter, commit-template
# install commit template and commit linternpx general-release install -c .release.yml# ofnpx general-release install -c .release.yml --commit-lint --commit-template# install commit templatenpx general-release install -c .release.yml --commit-template# install commit template on the specified filenpx general-release install -c .release.yml --template ./commit-template -
Uninstall the Tools: commit-linter, commit-template
# uninstall commit template and commit linternpx general-release uninstall# ofnpx general-release uninstall --commit-lint --commit-template# uninstall commit templatenpx general-release uninstall --commit-template -
Print Usage
npx general-release -hnpx general-release deploy -hnpx general-release preview -hnpx general-release validate -hnpx general-release install -hnpx general-release uninstall -h
Plugin API
-
Usage
general-release/bin/bin.sh -p "github -f general-release.zip --debug" -p "npm --debug" -p "coustom.sh --debug" -
./src/plugin.sh
- Methods
Name | Type | Description |
---|---|---|
bootstrap |
function(...) |
Running the plugin, bootstrap "$@" |
plugin_state |
function() |
Print running state of the plugin |
print_usage |
function() |
Print usage |
plugin_debug |
function(msg, ...) |
Print debug |
plugin_info |
function(msg, ...) |
Print info |
plugin_warn |
function(msg, ...) |
Print warn |
plugin_error |
function(msg, ...) |
Print error |
plugin_exit_error |
function(int exit_code?, msg, ...) |
Exit and print error |
plugin_exit_erron |
function(int condition?,int exit_code?, msg, ...) |
Exit and print error on condition != 0 |
- Extensions
Name | Type | Description |
---|---|---|
plugin_name |
string |
The plugin name |
plugin_arg |
function(opt_name, opt_value) |
Option parser of the plugin |
plugin_init |
function(hook) |
Initial callback of the plugin, called before execute hook |
plugin_{hook} |
string |
Command of the plugin hook |
plugin_usage |
function() |
Print usage message |
plugin_options |
function() |
Print plugin options |
- Plugin Context
Name | Type | Description |
---|---|---|
hook |
string | The plugin hook |
env_file |
file path | Output the release variables(branch , rp ) on load hook |
git_repo |
string | Git repository url |
branch |
string | Branch name |
tag_prefix |
string | Prefix of the git-tag |
prev_tag |
string | The last release git-tag |
tag |
string | Release git-tag |
version |
string | Release version |
channel |
string | Release channel |
prerelease |
string | Pre-release id |
release_note |
string | Release note |
dry_run |
"true" | Is dry run |
DEBUG |
"true" | Is debug mode |
COLOR_LOG |
"true" | Is color log mode |
Plugin Hooks
Hook Name | Description |
---|---|
load |
On release loading, output the release variables(branch , rp ) to $env_file |
version |
Called after release version analyzed |
before_deploy |
Called before deploy |
deploy |
Called on deploy |
after-deploy |
Called after deploy |
deploy-failed |
Called after deploy |
How to write a custom plugin ?
#!/bin/bash # include plugin libary source $(dirname $BASH_SOURCE)/../lib/plugin.sh # the plugin name plugin_name="plugin name" # command of the plugin hooks plugin_load="hook_load"plugin_version="hook_version"plugin_before_deploy="print_state && hook_before_deploy"plugin_deploy="hook_deploy" # the option parser test_option1=test_option2= # print the options color_log "<g> --test1 [string] Test string option --test2 [enable] Test enable option"} # print the plugin state # initial plugin before execute hook # do something ... } # example hook[load] # example hook[version] # example hook[before-deploy] # example hook[deploy] # bootstrap the plugin bootstrap "$@"
Plugins
Gzip Plugin
Archive files by tar
-
Usage
Usagegzip [<options>] [<path>...]Plugin Options-o,--output [string] Write the archive to this file(.tar.gz)-d,--dry-run [enable] Skip publishing, default: false--debug [enable] Enable debug logging, default: false--no-color [enable] Disable the color output, default: false-h,--help Print usage
NPM Plugin
Publish a npm package
-
Usage
Usagenpm [<options>]Plugin Options-r,--registry [string] NPM registry URL, default: https://registry.npmjs.org/-a,--access [string] Package access, default: public-t,--token [string] NPM auth token, default: ENV:NPM_TOKEN-d,--dry-run [enable] Skip publishing, default: false--debug [enable] Enable debug logging, default: false--no-color [enable] Disable the color output, default: false-h,--help Print usage
GitHub Plugin
Create a release at gitHub
-
Usage
Usagegithub [<options>]Plugin Options-f,--file [string] Add a publish file-t,--token [string] GitHub auth token, default: ENV:GITHUB_TOKEN-d,--dry-run [enable] Skip publishing, default: false--debug [enable] Enable debug logging, default: false--no-color [enable] Disable the color output, default: false-h,--help Print usage
Appveyor Plugin
Write Build Details on Appveyor
-
Usage
Usageappveyor [<options>]Plugin Options-d,--dry-run [enable] Skip publishing, default: false--debug [enable] Enable debug logging, default: false--no-color [enable] Disable the color output, default: false-h,--help Print usage