Wrap up 1.5

doc/gulp.md

@@ -1,5 +1,11 @@
 # Gulp support
 
+You can invoke Nerdbank.GitVersioning from a gulp task to get
+version information and even to automatically stamp your NPM packages.
+
+The following gulp script will update your package.json file's version
+property with the package version to build.  
+
 ```js
 var gulp = require('gulp');
 var nbgv = require('nerdbank-gitversioning')
@@ -8,3 +14,58 @@ gulp.task('default', function() {
     return nbgv.setPackageVersion();
 });
 ```
+
+The recommended pattern is to create your NPM package from another directory
+than your source directory so that the package.json can be version-stamped
+without requiring a change to your source files.
+In your checked-in version of package.json, set your `version` property to
+`0.0.0-placeholder`:
+
+```json
+{
+  "name": "your-package",
+  "version": "0.0.0-placeholder",
+}
+```
+
+Then write a gulp script that copies your files to package into another folder
+and stamps the version into that folder.
+
+```js
+const outDir = 'out';
+
+gulp.task('copyPackageContents', function() {
+    return gulp
+        .src([
+            'package.json',
+            'README.md',
+            '*.js'
+        ])
+        .pipe(gulp.dest(outDir));
+});
+
+gulp.task('setPackageVersion', ['copyPackageContents'], function() {
+    var nbgv = require(`./${outDir}`);
+    // Stamp the copy of the NPM package in outDir, but use this
+    // source directory as a reference for calculating the git version.
+    return nbgv.setPackageVersion(outDir, '.');
+});
+
+gulp.task('package', ['setPackageVersion'], function() {
+    return ap.execAsync(`npm pack "${path.join(__dirname, outDir)}"`, { cwd: outDir });
+});
+
+gulp.task('default', ['package'], function() {
+});
+
+``` 
+
+When you run your gulp script, the out directory will contain a package
+with a package.json file with a specific version field, such as:
+
+```json
+{
+  "name": "nbgv-trial",
+  "version": "1.0.15-g0b1ed99829",
+}
+```

doc/versionJson.md

@@ -7,7 +7,7 @@ Here is the content of a sample version.json file you may start with:
 ```json
 {
   "$schema": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/master/src/NerdBank.GitVersioning/version.schema.json",
-  "version": "1.0.0-beta"
+  "version": "1.0-beta"
 }
 ```
 
@@ -21,7 +21,7 @@ The content of the version.json file is a JSON serialized object with these prop
 
 ```js
 {
-  "version": "x.y.z-prerelease", // required
+  "version": "x.y-prerelease", // required
   "assemblyVersion": "x.y", // optional. Use when x.y for AssemblyVersionAttribute differs from the default version property.
   "buildNumberOffset": "zOffset", // optional. Use when you need to add/subtract a fixed value from the computed build number.
   "publicReleaseRefSpec": [
@@ -43,7 +43,6 @@ The content of the version.json file is a JSON serialized object with these prop
 
 The `x` and `y` variables are for your use to specify a version that is meaningful
 to your customers. Consider using [semantic versioning][semver] for guidance.
-The `z` variable should be 0.
 
 The optional -prerelease tag allows you to indicate that you are building prerelease software.
 

src/nerdbank-gitversioning.npm/README.md

@@ -1,4 +1,18 @@
 Nerdbank.GitVersioning
 ======================
 
-See our [online README](https://github.com/AArnott/Nerdbank.GitVersioning/blob/master/readme.md)
+With this package, and a version.json file to express your version number
+checked into the root of your git repo:
+
+```json
+{
+  "version": "1.0-beta"
+}
+```
+
+Your NPM packages and other builds can be automatically stamped with a
+version that precisely describes the git commit that built it.
+
+See our [project README][GitHubREADME] for more information.
+
+[GitHubREADME]: https://github.com/AArnott/Nerdbank.GitVersioning/blob/master/readme.md

src/nerdbank-gitversioning.npm/ts/index.ts

@@ -69,7 +69,7 @@ export async function getVersion(projectDirectory?: string): Promise<IGitVersion
 /**
  * Sets an NPM package version based on the git height and version.json.
  * @param packageDirectory The directory of the package about to be published.
- * @param srcDirectory The directory of the source code behind the package, if different. 
+ * @param srcDirectory The directory of the source code behind the package, if different than the packageDirectory. 
  */
 export async function setPackageVersion(packageDirectory?: string, srcDirectory?: string) {
     packageDirectory = packageDirectory || '.';

version.json

@@ -1,6 +1,6 @@
 {
   "$schema": "src\\NerdBank.GitVersioning\\version.schema.json",
-  "version": "1.5-rc",
+  "version": "1.5",
   "assemblyVersion": {
     "precision": "revision"
   },