@johnls/stampver
v2.0.6
Published
Version stamping tool
Downloads
12
Readme
Version Stamping Tool
Overview
This is a tool for updating version information in software projects. It stores version information in a JSON file at the root of the project. The file also contains information on how to update the various files within the project that need to contain version information. This keeps version information centralized in one location but also available where it is needed in your application. The version file also completely specifies how versioning works in the project and the behavior can be fully costomized. The tool has no opinion on how you do your versioning.
For this project, we had the following goals. We must be able to:
- Look at version file and see the list of affected files and the current version information clearly.
- Be able to fully customize the format of version numbers and update strategy.
- Reliably update any source code text file with new version information in-place.
- Be able to write-new version files.
- Be able to copy-in specific files related to versioning and build types.
The tool supports Semantic Versioning easily, but it can also support the many other types of versioning strategies in use today. The version file can also contain other arbitrary and useful data such as copyright information and project names.
Installation
Install it globally with:
npm install -g @johnls/stampver
With Node 8.0 and above you can just run it with npx
:
npx @johnls/stampver ...
Usage
To run tool the and check everything is set up correctly run:
stampver --help
You'll need to create a version.json5
file in the root of your project. See the next section on how to do this. Then you can do a dry run update by running:
stampver <version-operation>
where version-operation
is something you define in your version.json5
. The program does the following:
- Read the
version.json5
file in - Do any dynamic calculations of version information, such as generating a date based
build
value. - Increment or do some other operation on the
vars
information as specified on the command line - Update a list of files with the new version information using regular expression search & replace, or directly write files or copy specific files into place.
- Write out the
version.json5
file with updatedvars
version.json5
File Format
The file is in JSON5 format with an object at the root containing the following properties. You can examine and copy this projects version.json5
file for a starting point.
vars
A list of strings containing version information. major
, minor
, patch
, build
and revision
are common but not required.
calcVars
A list of interpolated strings that can calculate additional variables in the run context.
A now
variable is automaticall added to run context containing year
, month
, day
, hour
, minute
and second
properties for the time the program is run. The tz
variable, if present in vars
, must contain a TZ database name. This will be used to localize the now
variable.
An env
is automatically added containing a snapshot of process.env
.
operations
This is a list of scripts that modify the run context. Only one operation is run as specified on the command line.
targets
This is an array of objects containing files
, description
, action
properties. The files in the files
array will all be updated. Any paths are relative to the version.json5
file directory.
description
is only for informational purposes.
There are 3 types of action
updates
Updates is an array of objects. Each object contains search
and replace
fields. There can be multple updates per target file. The search
string is a regular expression which can contain named matches. The replace
string is a script that generates the replacement text if search
matches.
write
The write
property is a script that generates the contents of the target file.
copyFrom
The copyFrom
property is a script that generates the name of a file to copy from.
Run Context
The calcVars
, operation
, search
, replace
, write
and copyFrom
fields allow you to specify a string or an embedded JavaScript code. Embedded code is specified by putting {...}
around the entire string. For example:
{
operations: {
incrMajor: "{major += 1; minor = 0}",
}
}
The incrMajor
operation will add one to the major
variable and set minor
to zero. These scripts will be executed, or interpolated, using the NodeJS VM package using a shared global run context. This context is created once and used throughout the script. Scripts can access this run context and read or modify the values of earlier script actions. The context lifetime proceeds as follows:
- The run context is initialized with an
env
variable containing a snapshot ofprocess.env
- A
now
variable is added (see below). If thetz
variable is present the values innow
are specific to thetz
time zone. - All other
vars
properties are set as variables in the context.vars
variables are not expected to contain JavaScript i.e. they are constants. calcVars
are assumed to be script. They are interpolated and can update the run context.operations
are assumed to be script. The one selected on the command line is interpolated.- A
targets
are run the following can affect context:updates
: as eachsearch
completes any captured variables are added to the context, e.g.begin
andend
are common captures. Thereplace
value is interpolated. It's common to use a JS template literal to construct thereplace
string. Capture variables are removed from the context after each update is performed.with
: the contents of the file to be written are interpolated.copyFrom
: the path name of the file that is to be copied are interpolated
All JS String operations are available as well as Math
and anything that does not need to be require
'd.
The interpolation feature is meant to be used to make the tool adaptable to different versioning strategies. You could get yourself in a real mess if you try to do anything too crazy. Check the source code if in doubt.
About
stampver
is written in TypeScript and built to target NodeJS 10 or above.
I've used my own fork of JSON5 for the version file format. JSON5 is easy to type and maintain. The fork includes the ability to get line and column information for the parsed JSON5 to provide for better error messages.
I've used XRegExp because it supports named groups. Shields.io provides the badges.