Update CLI revert, tag; API jobs

website/content/api-docs/jobs.mdx

@@ -1831,7 +1831,11 @@ The table below shows this endpoint's support for
 - `JobID` `(string: <required>)` - Specifies the ID of the job. This is
   specified as part of the path.
 
-- `JobVersion` `(integer: 0)` - Specifies the job version to revert to.
+- `JobVersion` `(integer: 0)` - Specifies the job version to revert to. Use this
+  or `TaggedVersion`.
+
+- `TaggedVersion` `(string: "")` - Specifies the tag name of the job version you
+  want to revert to. Use this or `JobVersion`.
 
 - `EnforcePriorVersion` `(integer: nil)` - Optional value specifying the current
   job's version. This is checked and acts as a check-and-set value before
@@ -1849,13 +1853,24 @@ access. This is specified as a query string parameter.
 
 ### Sample Payload
 
+This example specifies the version.
+
 ```json
 {
   "JobID": "my-job",
   "JobVersion": 2
 }
 ```
 
+This example specifies the tagged version.
+
+```json
+{
+  "JobID": "my-job",
+  "TaggedVersion": "golden-version"
+}
+```
+
 ### Sample Request
 
 ```shell-session
@@ -2705,21 +2720,21 @@ This endpoint creates a tag for a job version.
 
 ```json
 {
-  "Version": 2,
+  "Version": 0,
   "Description": "The version we can roll back to."
 }
 ```
 
 ### Sample Request
 
-This example creates a tag named "golden-version" for version two of the
-"ecommerce-site" job.
+This example creates a tag named `golden-version` for version zero of the
+`hello-world` job.
 
 ```shell-session
-curl -X POST \
- localhost:4646/v1/job/ecommerce-site/versions/golden-version/tag \
+$ curl -X POST \
+ localhost:4646/v1/job/hello-world/versions/golden-version/tag \
  -H "Content-Type: application/json" -d \
- '{"Version": 2, "Description": "The version we can roll back to."}'
+ '{"Version": 0, "Description": "The version we can roll back to."}'
 ```
 
 ### Sample Response
@@ -2750,10 +2765,10 @@ This endpoint deletes a job version tag.
 
 ### Sample Request
 
-This example deletes the tag named "golden-version" from the job "ecommerce-site".
+This example deletes the `golden-version` tag from the `hello-world` job.
 
 ```shell-session
-curl -X DELETE localhost:4646/v1/job/ecommerce-site/versions/golden-version/tag -H "Content-Type: application/json"
+$ curl -X DELETE localhost:4646/v1/job/hello-world/versions/golden-version/tag -H "Content-Type: application/json"
 ```
 
 ### Sample Response

website/content/docs/commands/job/revert.mdx

@@ -27,13 +27,14 @@ authentication.
 
 ## Usage
 
-```plaintext
+```shell-session
 nomad job revert [options] <job> <version|tag>
 ```
 
 The `job revert` command requires two inputs, the job ID and the version or tag
-of that job to revert to.  If you specify the version number,  Nomad reverts the
-job to the exact version number. If you specify a version tag, Nomad reverts the job to the version with the given tag.
+of that job to revert to.  When you specify a version number, Nomad reverts the
+job to the exact version number. Alternately, when you specify a version tag,
+Nomad reverts to the version with that tag.
 
 When ACLs are enabled, this command requires a token with the `submit-job`
 capability for the job's namespace. The `list-jobs` capability is required to

website/content/docs/commands/job/tag.mdx

@@ -28,8 +28,7 @@ Use these optional general options with the subcommands.
 
 ## Apply
 
-Use `job tag apply` to save a job version. Nomad does not garbage collect saved
-job versions. You can [diff] and [revert] saved versions.
+Use `job tag apply` to create or modify a version tag.
 
 ### Apply usage
 
@@ -45,25 +44,25 @@ nomad job tag apply [options] <job_id>
 
 ### Apply examples
 
-This example tags the latest version of the job "ecommerce-site".
+This example tags the latest version of the job `hello-world`.
 
 ```shell-session
-nomad job tag apply -name "golden-version" \
+$ nomad job tag apply -name "golden-version" \
 		-description "The version we can roll back to." \
-    ecommerce-site
+    hello-world
 ```
 
-This example tags version 3 of the job "ecommerce-site".
+This example tags version zero of the job `hello-world`.
 
 ```shell-session
-nomad job tag apply -version 3 \
+$ nomad job tag apply -version 0 \
       -name "golden-version" \
-      ecommerce-site
+      hello-world
 ```
 
 ## Unset
 
-Use `nomad job tag unset` to remove a tag from a job version. This command requires a job name and a tag name.
+Use `nomad job tag unset` to delete a tag from a version. This command requires a job name and a tag name.
 
 ### Unset usage
 
@@ -77,10 +76,10 @@ nomad job tag unset [options] <job_id> -name <tag>
 
 ### Examples
 
-This example removes the "golden-version" tag from the "ecommerce-site" job.
+This example removes the `golden-version` tag from the `hello-world` job.
 
 ```shell-session
-nomad job tag unset ecommerce-site -name "golden-version"
+$ nomad job tag unset hello-world -name "golden-version"
 ```
 
 [diff]: /nomad/docs/commands/job/history/

website/content/docs/concepts/job.mdx

@@ -96,6 +96,34 @@ zero. Nomad's garbage collector has not yet removed or purged the job.
 The `Stopped` status indicates that a user has manually stopped the job.
 Nomad's garbage collector has not yet removed or purged the job.
 
+## Job versions
+
+@TODO - still working on this section!!
+
+Describe, pin, prevent garbage collection
+
+Nomad does not garbage collect saved
+job versions. You can [diff] and [revert] saved versions.
+
+version name is unique per job
+
+Nomad jobs have a version history that is stored in state. Over time, Nomad
+garbage collects terminal versions. You can run commands like `nomad job
+history` to see differences between past versions of jobs and their immediate
+predecessors. Additionally, you can run `nomad job plan` to see the hypothetical
+difference of an update against the current job version.
+
+These “diff” views are useful tools in the “measure twice, cut once” vein of configuration management, as they help users get a granular view of not just what’s about to change in the job spec they’ve modified, but also the rendered differences after environment variables, etc. are applied. These tools help users make better decisions about updating jobs and are critical parts of several Nomad workflows (for example: running a job through the Web UI requires going through a plan phase so the user sees a job diff before they’re able to submit the update).
+
+Jobs can have an unlimited number of versions. Sometimes these versions are slow-moving (for example, an operator changes the image tag of their docker-run application when there is a major version update), and other times they are very fast (for example, a user writes their own auto-scaler that makes template configuration changes based on external factors).
+
+
+When you update and resubmit a job, Nomad increases the version number.
+
+Jobs can have an unlimited number of versions.
+
+Tag names must be unique per job.
+
 ## Related resources
 
 Refer to the following Nomad documentation pages for more information about