appversion

AppVersion

AppVersion is intended as an extension of npm version and is a cli tool for keep track the version, build, status and commit of your javascript application.
The project is built following semver guidelines.

Usually a project has different configuration/package-manager files, such as package.json, and can be really tedious update the project number in every file.
Here comes to help AppVersion, an easy to use command line tool who updates all the files for you.
In addition AppVersion keeps track of the build date and number.

The tool creates a json file named appversion.json in the root of your project with the following structure:

{
  "version": {
    "major": 0,
    "minor": 0,
    "patch": 0
  },
  "status": {
    "stage": null,
    "number": 0
  },
  "build": {
    "date": null,
    "number": 0,
    "total": 0
  },
  "commit": null,
  "config": {
    "appversion": "x.y.z",
    "markdown": [],
    "json": [],
    "ignore": []
  }
}

As you can see, the version is divided in major, minor and patch, the build is divided in date, number and total, in addition, there's the status, who is divided in stage field, who can assume stable|rc|beta|alpha (the first letter can be Uppercase) value and number.

Then, there's the config filed, divided in appversion, that is used by AppVersion for check if the json is at the latest version, markdown field where you can put all the markdown files that you want to keep updated (see here for more information).
The last two fields inside config are, json, that is the list of the json files who appversion must update when you change the version number, and ignore, that is the list of the folders that AppVersion must ignore.

Needs Node.js >= 4.0.0

Install

Install the tool globally:

npm install appversion -g

If you want to access the appversion.json inside your application, install the module also locally:

npm install appversion --save

Usage

CLI:

$ apv <cmd> <args>

Commands list:

cmd	args	description
update	major	Updates major number.
	minor	Updates minor number.
	patch	Updates patch number.
	build	Updates build number.
	commit	Updates commit code.
set-version	x.y.z	Sets a specific version number.
set-status	stable	Set the status to stable.
	rc	Set the status to rc.
	beta	Set the status to beta.
	alpha	Set the status to alpha.
generate-badge	version	Generates the .md code of a shield badge with the version of your application
	status	Generates the .md code of a shield badge with the status of your application
init		Generates the appversion.json file.
help		Prints the commands list.

Some usage examples:

$ apv update minor
$ apv set-version 1.3.2
$ apv set-status rc.2

By default, AppVersion updates the "version" field in package.json; if you want to update the "version" field in more json files, just add the file name inside appversion.json in the json array field.

AppVersion looks recursively inside all the subfolders of your project for json files, by default it ignores node_modules, bower_components and .git folders; if you want to ignore more folders just add the folder name inside appversion.json in the ignore array field.
If you want that AppVersion ignores all the subfolders in your project, just put "*" inside the ignore array.

AppVersion can provide you a wonderful shield badge with the version of your application that you can put in you .md file, like what you see at the top of this file.
Generate the badge is very easy, just type apv generate-badge version for the version badge and apv generate-badge status for the status badge and copy the output inside your .md file, then add the name of the md file (with the extension) inside the markdown array field in appversion.json, from now AppVersion will keep updated the badges every time you update your application.
This feature make use of the amazing service shields.io.

In app:

Function
getAppVersion()	async
getAppVersionSync()	sync
composePattern()	async
composePatternSync()	sync

getAppVersion(callback)

Returns the content of appversion.json as a object.
This is the asyncronous version, so you must pass a callback to the function.

getAppVersionSync()

Returns the content of appversion.json as a object.
This is the syncronous version, so you don't need to pass a callback to the function.

composePattern(pattern, callback)

Return a string with the version following the pattern you passed as a input.
pattern:

Pattern	description
M	version.major
m	version.minor
p	version.patch
S	status.stage
s	status.number
n	build.number
t	build.total
d	build.date
c	commit
.	separator
-	separator

The pattern must be a string, for example a pattern could be 'M.m.p-Ss n-d'.
This is the asyncronous version, so you must pass a callback to the function.

composePatternSync(pattern)

Return a string with the version following the pattern you passed as a input.
The pattern string follow the same rules as above.
This is the syncronous version, so you don't need to pass a callback to the function.

Sometimes you want to have the version/build number accessible in your application, for this, you can use the module with a standard import:

// es5:
var apv = require('appversion')

console.log(apv.getAppVersionSync())
console.log(apv.getAppVersionSync().version)

apv.getAppVersion(function (err, data) {
  if (err) console.log(err)
  console.log(data)
})

console.log(apv.composePatternSync('M.m.p-Ss n-d'))

apv.composePattern('M.m.p-Ss n-d', function(ptt) {
  console.log(ptt)
})


// es6 - es2015:
import { getAppVersion, getAppVersionSync, composePattern, composePatternSync } from 'appversion'

console.log(getAppVersionSync())
console.log(getAppVersionSync().version)

getAppVersion((err, data) => {
  if (err) console.log(err)
  console.log(data)
})

console.log(composePatternSync('M.m.p-Ss n-d'))

composePattern('M.m.p-Ss n-d', (ptt) => {
  console.log(ptt)
})

Automating

If you are using npm scripts you can easily integrate AppVersion in your workflow, below you can find an example of a package.json:

...
"scripts": {
  "build": "<build command> && apv update build"
},
...

TODO

• Update status number
• Badge generator with the application version for the README.md.
• Move json, markdown, ignore and appversion inside config field
• Implement "New version" message
• Split the code in multiple files divided by function.
• When init is called, apv must create appversion.json with the same version number of package.json.
• Integration with GitHub
• SHA generator

Build

$ npm install
$ chmod u+x apv.js
$ npm test

$ ./apv.js <cmd> <args>

Contributing

If you feel you can help in any way, be it with examples, extra testing, or new features please open a pull request or open an issue.

The code follows the Standard code style.

---

License

The code is released under the GPLv2 license.

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non infringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.