@govtechsg/vtscripts
v1.0.0
Published
[![Build Status](https://travis-ci.org/zephinzer/version-tagging-scripts.svg?branch=master)](https://travis-ci.org/zephinzer/version-tagging-scripts)
Downloads
25
Maintainers
Keywords
Readme
Version Tagging Scripts
This package provides scripts that helps with managing semver versioning systems using git tagging.
Semver versioning is:
X . Y . Z
| | |-> patch version (bug fixes)
| |-> minor version (backward-compatible changes/additions)
|-> major version (backward-compatibility breaking changes)
Read more on semver at: http://semver.org/
Installation
NPM
Install this locally using:
npm i vtscripts --save-dev
Or globally:
npm i -g vtscripts
Git Submodule
Use this as a git
submodule. Install it by running the following in the root of your
project:
git submodule add https://github.com/zephinzer/version-tagging-scripts <./path/to/put/it/in>
Usage
By default, all scripts will print the debug output. They also come with a -q
or
--quiet
flag that can silence the debug output which you should use once you've tested
them out.
Details of all scripts can also be found via the -h
or --help
script.
IMPORTANT Call the scripts using
./script
instead ofbash ./script
, this allows the script to find itself relative to where you're calling it from and things will fail should you not do so. The necessary hashbangs have been added and they are labelled with#!/bin/sh
.
./iterate
When installed via
npm
, this script is available asvbump
.
The ./iterate
script should be enough for most continuous integration pipelines.
Run it anywhere in your pipeline that you need to up the version number.
To up the patch
version, use:
./path/you/put/it/iterate -q -i
To up the minor
version, use:
./path/you/put/it/iterate minor -q -i
To up the major
version, use:
./path/you/put/it/iterate major -q -i
./get-branch
This script outputs the current branch you are on.
./get-latest
When installed via
npm
, this script is available asvlatest
.
This script outputs the latest version you are on.
./get-next
When installed via
npm
, this script is available asvnext
.
This script outputs the next version you should be migrating to.
./init
When installed via
npm
, this script is available asvinit
.
This script checks for the presence of a git
tag that resembles x.y.z
where
x
is the major version, y
is the minor version, and z
is the patch version.
Should it fail to find such a git tag, it will initialize by adding a global
0.0.0
tag to your repository.
CI Software Integration Help
GitLab
Install it in your dev machine with:
git submodule add https://github.com/zephinzer/version-tagging-scripts <./path/you/wanna/add/submodule/to>
A new file .gitmodules
should appear. Verify that it looks like
[submodule './path/you/added/submodule/to']
path = ./path/you/added/submodule/to
url = https://github.com/zephinzer/version-tagging-scripts
We use this script with GitLab by installing this repository as a git
submodule.
In a build
phase in your scripts
property, add the following:
...
stage: build
...
artifacts:
path:
- ./path/you/added/submodule/to
...
scripts:
- git submodule deinit -f .
- git submodule init
- git submodule update --init
- git submodule sync
- ...
...
Note that using the ssh://
version for this repo when adding the submodule WILL NOT WORK
and will corrupt whichever runner it runs on.
Incase you corrupt a runner, you'll need to access the directory containing your
project builds and manually run deinit
and change the .gitmodules
file to direct it
to the HTTPS version of this repository. Main symptom of a corrupt runner will be during
the fetch/clone phase of a job, you'll see some lines that look like:
Fetching changes...
fatal: [../]+.git/modules/[./path/you/added/submodule/to] is not a git repository
Or something to that effect. No tests have been run, before_script
has not run either.
Play With It
The ./utils
directory contains some tools to get you started on how this works.
Setup Branches
Run the following to set up a traditional CI pipeline consisting of
dev
, ci
, qa
, uat
, staging
and production
branches/environments:
#> ./utils/branch_setup
You should find yourself on the _dev
branch. They will be prefixed with an underscore
incase you forget that they are just test example environments.
Setup Pipeline
Run the following to add commits to the relevant branches:
#> ./utils/pipeline_setup
This will add commits to the environments that simulate an actual pipeline with
_production
having only 1 commit and _dev
having all 6 commits (1 for each
environment/branch).
Play With It
Run ./iterate -q -i
on the _dev
branch (which you should be on). This will initialize
the versioning in _dev. Check out the versions available with:
#> git tag -l --merged
There should be 0.0.0
and 0.0.1
. Great.
Now checkout the _ci
branch and check the branch for tags with:
#> git tag -l --merged
There should be no tags. Now do a rebase from the _dev
branch into your _ci
branch:
#> git rebase _dev
Run the tag checking command again:
#> git tag -l --merged
You should now see 0.0.0
and 0.0.1
because the tags associated with the HEAD
commit in the _dev
branch should have been played to _ci
and _ci
now has the
commits from _dev
. Verify this yourself with git log -n 1
. Both should match.
Enough Games
Run the following to revert all test/example branches:
#> ./utils/branch_teardown
Inspiration
We needed a standardised way to add versioning to our packages. The primary way we use it internally is in a GitLab environment.
Testing
We use Docker to test the code so that we can check if certain expected features are available.
Run the tests using:
#> ./test
Supported Versions
Git
- Git 1.8.5
Contributing
Feel it's lacking something? Feel free to submit a Pull Request. Got it to work with another CI software? Feel free to add to this readme's CI Software Integration Help section.
Cheers!