gulp-codename

Gulp.js Plugin utility to include a codename for your application based on version (up-to v10.X.X-X).

This works great alongside version bump utility: gulp-bump for keeping your version numbers and names up-to-date with each build.

Included codenames and patch names created with the help of the excellent codenamegenerator.com website.

We created "grunt-codename" in late 2013; which has had over 1,500 downloads to date, but as we prefer to use Gulp.js now, it was about time we sorted this out.

Example

The utility will create a codename and a patch name based on your version number.

Version "0.0.1" will generate:

”codename": "Perseus Amber"
”patchname": "Saiga"

So; effectively your version is "0.0.1 Perseus Amber (Saiga)".

Version "0.0.2" will generate:

"codename": "Perseus Amber"
"patchname": "Ithomiid"

So; effectively your version is "0.0.1 Perseus Amber (Ithomiid)".

There is no patch name for "0" ("X.X.0") so Version * “0.1.0”* will generate:

"codename": "Bronze Marklar"
"patchname": ""

So; effectively your version is "0.1.0 Bronze Marklar".

Source code

To view the source; check out the git repository:

https://github.com/scriptwerx/gulp-codename

Getting started

This plugin requires gulp.

Once you're familiar with that process, you may install this plugin with this command:

npm install gulp-codename --save-dev

Once the plugin has been installed, it may be enabled inside your gulpfile with this line of JavaScript:

var codename = require('gulp-codename');

The project follows the SemVer guidelines for version numbers; specifically following: ‘1.2.3-1’ being ‘MAJOR.MINOR.PATCH-BUILD’.

N.B. The supplied codenames and patch names only include support for single-digit numbers used for minor and patch of the version field (and major up to 10) - you must supply your own custom codenames and patch names if you can't handle this restriction (but that's a lot of names)!

The "codename" task

Overview

In your project's gulpfile.js, add a section named ‘codename’.

gulp.task('codename', function() {
 return gulp.src('./package.json')
   .pipe(codename())
   .pipe(gulp.dest('./'));
});

codename allows to set the codename and patch name based on the version number of the configuration file (package.json) in your project. Only JSON files are supported, and each file must have a ‘version’ field compliant to SemVer guidelines; specifically following: ‘1.2.3-1’ being ‘MAJOR.MINOR.PATCH-BUILD’.

Remember: The supplied codenames and patch names only include support for single-digit numbers used for minor and patch of the version field (and major up to 10) - you must supply your own custom codenames and patch names if you can't handle this restriction (but that's a lot of names)!

Example JSON

codename is designed to update your package.json, manifest.json or any other JSON file with a "version" field (configured as noted above).

An example of a manifest.json file is below:

{
 "name": "My Test Application",
 "version": "1.3.2-16",
 "codename": "",
 ”patchname": "",
 "description": "A test application for me."
}

Once codename has been used (with patchNames enabled); the manifest.json file would be updated automatically as follows:

{
 "name": "My Test Application",
 "version": "1.3.2-16",
 "codename": "Honiara Nimitz",
 "patchname": "Ithomiid",
 "description": "A test application for me."
}

Default Options

Running the task in this way, the ‘codename’ and ‘patchname’ fields of each source file will be automatically changed to the correct codename and patch name for the build release.

gulp.task('codename', function() {
 return gulp.src('./package.json')
   .pipe(codename())
   .pipe(gulp.dest('./'));
});

Custom Options

An options Object is supported:

• codenames: (File) path to custom codenames JSON file.
• patchname: (Boolean) Include patch name.

Running the task in this way, the ‘codename’ field of each source file will be changed to the correct codename but patch name will not be included.

The names contained within the user-supplied myCodenames.json file will be used.

gulp.task('codename', function() {
 return gulp.src('./package.json')
   .pipe(codename({
     codenames: 'myCodenames.json',
     patchname: false
   }))
   .pipe(gulp.dest('./'));
});

Use with gulp-bump

You can add the codename task alongside your bump task as follows:

gulp.task('bump', function() {
 return gulp.src('./package.json')
   .pipe(bump({ type: 'patch' }))
   .pipe(codename())
   .pipe(gulp.dest('./'))
});