Update docs to reflect recent changes (#40)

* Document backport releases
* Correct format of root version and explanation for how it gets
  incremented

Author: mcmire

docs/usage-monorepo-fixed.md

@@ -1,5 +1,7 @@
 # Using the tool in a monorepo with fixed versions
 
+> <table><tr><td><b>👋 HEADS UP!</b> This is an aspirational document; the tool does not support this workflow yet.</td></tr></table>
+
 For a monorepo using a "fixed" versioning strategy, the tool needs to know not only which version you want to release, but also which packages you want to release.
 
 Start by running:

docs/usage-monorepo-independent.md

@@ -1,6 +1,13 @@
 # Using the tool in a monorepo with independent versions
 
-For a monorepo using an "independent" versioning strategy, the tool needs to know which packages you want to release and how to set the version for each package.
+For a monorepo using an "independent" versioning strategy, the tool needs to know two things:
+
+1. Which packages you want to release and how to set the version for each package.
+2. Whether or not you are creating a backport release as opposed to an "ordinary" release.
+
+## Ordinary release
+
+Typically, a new release will follow the most recent release (that is, the changes within the release are applied to the code in the most recent release). We call this an _ordinary_ release.
 
 Start by running:
 
@@ -33,9 +40,26 @@ Once you've filled out the release spec, save and close it, and the tool will co
 
 At this point, the tool will:
 
-1. Calculate a new release version by extracting the build number from the current version, incrementing it, and combining it with the current date, then setting the `version` of the root package to this new version.
+1. Calculate a new release version by incrementing the "ordinary" (first) number of the current version, then set the `version` of the root package to this new version.
 2. Go through each workspace package specified, and:
-   1. Adjust the `version` of the package to the version specified.
+   1. Calculate a new version of the package that you specified in the release spec, then set the `version` of the package to this new version.
    2. Read the Git history of the repo to extract the names of the commits which have made any changes to any files within the package since the Git tag that corresponds to the current version of the package.
    3. Add a new section to the changelog for the package which is titled by the release version and which lists the commits gathered.
-3. Commit the changes to a new branch called `release/<release-version>`, where `<release-version>` is the version calculated in step one (e.g. `release/2022.6.8-123`), and switch to that branch.
+3. Commit the changes to a new branch called `release/<release-version>`, where `<release-version>` is the version calculated in step one (e.g. `release/5.0.0`), then switch to that branch.
+
+## Backport release
+
+Sometimes you will need to create a release which contains a change, such as an important fix, to a pre-existing release. We call this a _backport_ release.
+
+The process for creating a backport release works the same as an ordinary release, except before you run the tool, you will switch to a branch that represents an "alternative timeline" based off a past version (for instance, you might have previously cut a branch that continues the 1.x line of the project, even though the latest version is 2.x).
+
+> **Note**
+> It's necessary to be on another branch and not the main line, because `create-release-branch` uses the version of packages as they exist on the current branch, and not the latest published versions, to determine the release version and to populate changelogs correctly.
+
+Once on this branch, run:
+
+```
+create-release-branch --backport
+```
+
+In this case, the new release version will be calculated by incrementing the "backport" (second) number of the current version, but the versions and changelogs of workspace packages will still be updated according to the release spec.

docs/usage-polyrepo.md

@@ -1,5 +1,7 @@
 # Using the tool for a polyrepo package
 
+> <table><tr><td><b>👋 HEADS UP!</b> This is an aspirational document; the tool does not support this workflow yet.</td></tr></table>
+
 For a package within a polyrepo architecture, the tool needs to know the new version of the package you want to release. This can happen one of two ways:
 
 1. You can have the tool determine the release version automatically by bumping the major, minor, or patch part of the current version.