Document migration techniques

Author: AArnott

doc/migrating.md

@@ -0,0 +1,38 @@
+# Migrating to Nerdbank.GitVersioning
+
+## Dealing with legacy version.txt or version.json files
+
+When you already have a version.txt or version.json file in your repo and want to use Nerdbank.GitVersioning,
+you may find that your build breaks when NB.GV tries to parse your version.txt or version.json file(s).
+
+Any such version.txt or version.json files in project directories with NB.GV installed, or any parent directory up to the repo root, must be removed in a commit *prior* to the commit that defines the new NB.GV-compliant version.json file. This will ensure that NB.GV will not discover the legacy files and try to parse them.
+
+It is important that you maintain that clean break where no commit with a NB.GV version.json file has an immediate parent commit with a legacy version file. A merge commit (like a pull request with your migration changes would create) will defeat your work by having the new version.json file and an immediate parent with the version.txt file (the one from your base branch). It is therefore mandatory that if you have such a legacy file, that when you're done validating the migration that you *directly push your 2+ commits to your branch* rather than complete a pull request. If your team's policy is to use pull requests, you can create one for review, but complete it by pushing the commits directly rather than letting the git service create the merge commit for you by completing the pull request. If the push is rejected because it is not a fast-forward merge, *rebase* your changes since a local merge commit would similarly defeat your efforts.
+
+Also note that any other open pull requests that are based on a commit from before your changes may also introduce the problematic merge commit by providing a direct parent commit path from the new version.json file to the legacy one. These open PRs must be squashed when completed or rebased.
+
+## Maintaining an incrementing version number
+
+When defining your new [version.json file](versionJson.md), you should set the version to be same *major.minor* version that you used before or higher.
+If you are matching the prior *major.minor* version and need the build height integer (usually the 3rd integer) of your version to start higher than the last version from your legacy mechanism, set the `"buildNumberOffset"` field in the version.json file to be equal to or greater than the 3rd integer in the old version. Note that the first build height will be *one more than* the number you set here, since the commit with your changes adds to the offset you specify.
+
+For example, suppose your last release was of version 1.2.4. When you switch to NB.GV, you may use a `version.json` file with this content:
+
+```json
+{
+  "version": "1.2",
+  "buildNumberOffset": 4
+}
+```
+
+After commiting this change, the first version NB.GV will assign to your build is `1.2.5`.
+
+When you later want to ship v1.3, remove the second field so that the 3rd integer resets:
+
+```json
+{
+  "version": "1.3"
+}
+```
+
+This will make your first 1.3 build be versioned as 1.3.1.

readme.md

@@ -12,7 +12,7 @@ This package adds precise, semver-compatible git commit information
 to every assembly, VSIX, NuGet and NPM package, and more.
 It implicitly supports all cloud build services and CI server software
 because it simply uses git itself and integrates naturally in MSBuild, gulp
-and other build scripts. 
+and other build scripts.
 
 What sets this package apart from other git-based versioning projects is:
 
@@ -28,7 +28,7 @@ You can install Nerdbank.GitVersioning into your projects via NuGet or NPM.
 * [NuGet installation instructions](doc/nuget-acquisition.md)
 * [NPM installation instructions](doc/npm-acquisition.md)
 
-You must also create [a version.json file](doc/versionJson.md) in your repo.
+You must also create [a version.json file](doc/versionJson.md) in your repo. See [migration notes](doc/migrating.md) if your repo already has a version.txt or version.json file from using another system.
 
 ## How to leverage version stamping and runtime information
 
@@ -59,7 +59,7 @@ the git 'height' of the version, and the git commit ID.
 ### Version generation
 
 Given the same settings as used in the discussion above, a NuGet or NPM package may be
-assigned this version: 
+assigned this version:
 
     1.0.24-alpha-g9a7eb6c819
 
@@ -86,7 +86,7 @@ The git commit ID does not represent an alphanumerically sortable identifier
 in semver, and thus delivers a poor package update experience for NuGet package
 consumers. Incrementing the PATCH with each public release ensures that users
 who want to update to your latest NuGet package will reliably get the latest
-version. 
+version.
 
 The git height is guaranteed to always increase with each release within a given major.minor version,
 assuming that each release builds on a previous release. And the height automatically resets when
@@ -98,14 +98,14 @@ It could be, but the git height serves as a pseudo-identifier already and the
 git commit id would just make it harder for users to type in the version
 number if they ever had to.
 
-Note that the git commit ID is *always* included in the 
+Note that the git commit ID is *always* included in the
 `AssemblyInformationVersionAttribute` so one can always match a binary to the
 exact version of source code that produced it.
 
 ### How do I translate from a version to a git commit and vice versa?
 
 A pair of Powershell scripts are included in the Nerdbank.GitVersioning NuGet package
-that can help you to translate between the two representations. 
+that can help you to translate between the two representations.
 
     tools\Get-CommitId.ps1
     tools\Get-Version.ps1