A fully automated handy CLI utility that takes care of releasing GitHub software projects, written in 100% pure bash.
It does several things that are typically required for releasing a Git repository:
The command ver-bump
will execute the following steps:
package.json
CHANGELOG.md
Step | Description | |
---|---|---|
Verify + Prepare Release | Process user arguments | Check and store CLI arguments supplied by user for later processing. |
Check commits | Verify some commits exist for release. | |
Determine Release Version | If <package.json> doesn't exist, warn + exit. If -v option is specified, set version from that.Or, grab from version from package.json .Suggest incremented version number in the form of MAJOR.MINOR.PATCH (incrementing PATCH ), as per Semver 2.0.0.Give the user the option to modify/confirm suggested version bump. | |
Check branch exist | Ensure a release branch with the chosen version number doesn't already exist, if so exit. | |
Check tag exists | Ensure a tag with the chosen version number doesn't exist, and exit if it does. | |
Create Release | Bump version number | Update semantic version number in package.json + stages changes. |
Generate changelog | Commits since the last release are automatically added to CHANGELOG.md , as well as new commit messages for files modified by this script itself. Stages changes for commit action later. | |
Create release branch | Create a branch with the name release-MAJOR.MINOR.PATCH and switch to it (following the Git branch-based workflow). | |
Commit changed files | Commits changes to package.json and CHANGELOG.md` (staged in the previous steps) to the release branch. | |
Create Git tag | Create a Git tag referencing the new release version. | |
Push | Optionally, push the release branch to origin. |
In order to use ver-bump
you need:
npm
and node
installedInstall the script globally via npm, and use it in any local Git repository to release your project:
$ npm install -g ver-bump
package.json
file in your project and it contains a "version": "x.x.x"
parameter$ ver-bump [-v <version no.>] [-m <release message>] [-j <file1>] [-j <file2>].. [-n] [-p] [-b] [-h]
-v <version number> Specify a manual version number
-m <release message> Custom release message
-f <filename.json> Update version number inside JSON files.
* For multiple files, add a separate -f option for each one,
* For example:
./ver-bump.sh -f src/plugin/package.json -f composer.json
-p <repository alias> Push commits to remote repository, eg `-p Origin`
-n Turns off automatic commit
* You may want to do that yourself, for example.
-b Don't create automatic `release-<version>` branch.
-c Disable updating CHANGELOG.md automatically with new commits
since last release tag.
-l Pause enabled for amending CHANGELOG.md
-h Show help message.
This example assumes that a
package.json
containsversion: "1.0.0"
, and the user is working in the branch to be released with pre-existing un-released commits.
This will create a new Git branch called release-1.0.1
and a Git tag named v1.0.1
:
Output:
Current version read from <package.json> file: 1.0.0
Enter a new version number or press <enter> to use [1.0.1]: <pressed enter>
āāāāāā
ā
Updated file <package.json> from 1.0.0 -> 1.0.1
ā
Updated [CHANGELOG.md] file
Make adjustments to [CHANGELOG.md] if required now. Press <enter> to continue.
Creating new release branch...
ā
Switched to branch 'release-1.0.1'
M CHANGELOG.md
M package.json
Committing...
ā
[release-1.0.1 ace8b1e] Updated package.json, Updated CHANGELOG.md, Bumped 1.0.0 ā> 1.0.1
2 files changed, 9 insertions(+), 1 deletion(-)
ā
Added GIT tag
Push tags to <origin>? [N/y]: n
āāāāāā
ā
Bumped 1.0.0 ā> 1.0.1
š Done!
$ ver-bump
After checking out the changes in the branch and confirming them, test the release, and push the release branch to your remote if you didn't choose to push it automatically. Alternatively, use $ ver-bump -p origin
to bypass the prompt and push the release branch anyway to the remote automatically.
If your code checks out, then open a Pull Request to merge the release branch into your develop
or main branch.
You can merge the release branch into your development branch or main branch like this, without fast-forwarding so that the branch topology is preseved as you're merging in a release branch that hasn't diverged (apart from new changes to CHANGELOG.md
and package.json
) and you want to ensure it's clearly evident when reading the history that a merge was performed, as opposed to a fast-forward merge, where new commits performed by the merge will become descendents of the last commit before the merge.
A release branch shouldn't normally diverge from the branch it was created during the time ver-bump
is operating, so a non-fastforward should be possible instead of a normal merge, which would simply looks like a new commit was made to the main or development branch.
$ git checkout develop # Switch to development branch from the new release branch
$ git merge --no-ff release-1.0.1 # Merge the new release branch to your development branch
This project uses bats to test the functionality of ver-bump.
To run the tests, first install the pre-requisites:
Linux/MacOS:
$ npm run tests:install
Windows:
$ npm run tests:install:windows
And finally, run the test suite:
$ npm run tests:run
Output:
ver-bump.bats
ā can run script
ā process-arguments: -h: display help message
ā process-arguments: -v: fail when not supplying version
ā process-arguments: -v x.x.x: succeed when supplying version
ā process-arguments: -m: fail when not supplying release note
ā process-arguments: -m <note>: succeed when supplying release note
ā process-arguments: -f: fail when not supplying filenames
ā process-arguments: -f <filename.json>: succeed with multiple filenames
ā process-arguments: -p: fail when not supplying push destination
ā process-arguments: -p <repo destination>: succeed when supplying a destination
ā process-arguments: -n: set flag to prevent committing at the end
ā process-arguments: -b: set flag to disable creating a release branch
ā process-arguments: -c: set flag to disable creating/updating CHANGELOG.md
ā process-arguments: -l: set flag to enable pausing after CHANGELOG.md is created
ā process-arguments: fail on not-existing argument
ā set-v-suggest: increments version
ā set-v-suggest: fails to increments non SemVer version
ā process-version: fail on entering non-SemVer input
ā process-version: patch of the version from json file should be bumped +1
ā do-packagefile-bump: can bump version in package.json + lock file
ā bump-json-files: can bump version in a json file
ā bump-json-files: can fail bumping a json file when a version already exists in file
ā bump-json-files: can fail bumping a json file when no version found inside it
ā check-branch-notexist: can detect branch DOES exist
ā check-branch-notexist: can confirm branch DOES'NT exist
ā do-branch: can create a release branch
ā do-tag: create a tag
ā check-tag-exists: check doesn't exist
ā check-tag-exists: check it exists
ā do-changelog: can create a CHANGELOG.md
30 tests, 0 failures
I'd love you to contribute to @jv-k/ver-bump
, pull requests are welcome for submitting issues and bugs!
Author: jv-k
Source Code: https://github.com/jv-k/ver-bump
License: MIT license.