Neurotic Pink Mongooses

    @govtechsg/vtscripts

    1.0.0 • Public • Published

    Version Tagging Scripts

    Build Status

    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 of bash ./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 as vbump.

    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 as vlatest.

    This script outputs the latest version you are on.

    ./get-next

    When installed via npm, this script is available as vnext.

    This script outputs the next version you should be migrating to.

    ./init

    When installed via npm, this script is available as vinit.

    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!

    Keywords

    none

    Install

    npm i @govtechsg/vtscripts

    DownloadsWeekly Downloads

    2

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    29 kB

    Total Files

    20

    Last publish

    Collaborators

    • isomer.govtech
    • gyunikuchan
    • gds_ace_dlt
    • gdsbot
    • gylsky
    • ryanoolala
    • dyihoon90