Edit text

Katie Horne · Katie Horne · commit 9f4c611698df · 2021-04-05T13:43:38.000-05:00
diff --git a/images/tags.md b/images/tags.md
@@ -8,58 +8,6 @@ target="_blank" rel="noreferrer noopener">Image tags</a> are variants of the
 original (or base) image. Users can publish new image tags containing updated
 dependencies and tooling useful for work on the project.
 
-## Image tag lifecycle
-
-Coder uses tags for images to determine which image a user intends create a
-workspace from. Examples of tags: 
-
-    ubuntu:rolling
-    ubuntu:20.04
-    codercom/enterprise-node:ubuntu
-    mycorp/myproject:v1
-
-For the first pair, they both refer to Ubuntu base images however the way each
-tag is used is quite different. The `:20.04` tag stays with that release and is
-updated with patches and fixes but not typically new functionality. For new
-functionality, the `:rolling` tag will move up to `:20.10` and eventually `:21.04`
-as the new versions are released. 
-
-In Coder, if a workspace is created using a `:20.04` style tag and the supported
-software moves on to require `:20.10`, the user will not be alerted. Coder will
-inform the developer when patches and updates are available so they can rebuild
-the workspace to get rid of the outdated versions. This is good for long-term
-support of software that has lengthy version cycles or multiple supported
-versions where jumping back to "last year's release" to investigate or hotfix
-can be expected.
-
-If the workspace is created from a `:rolling` or `:latest` sort of tag, the
-workspace will prompt to be rebuilt for the same patching and security updates
-but will also prompt for a rebuild when a major version increase happens. This
-may be preferred for support SaaS or mobile apps that update frequently and need
-to stay current for everyone. 
-
-For the `codercom/enterprise-node:ubuntu` image, the name denotes the company
-and software architecture ("node") while the tag specifies the base image.
-Without a version, it can be assumed that it will operate like a rolling
-tag. It also implies that other flavors such as `:centos` or `:arch` may be
-available if users prefer those. 
-
-Finally, the `mycorp/myproj:v1` image can help make it clear that the image is
-tightly associated with a specific project's major version. The `:v1` tag can
-be applied to the most recent build for that image while more specific `:v1.3`
-or even `:v1.3.1` tags allow users to summon a very specific tag. 
-
-#### Summary
-
-*  `latest` will always prompt the user to rebuild whenever the tag is placed 
-   on a new image
-*  `v1` will prompt the user to rebuild whenever the tag is placed on a new 
-   image but shouldn't move to `v2`
-*  `ubuntu` or another sort of tag will behave as `latest` but implies the
-   existence of alternatives
-*  `v1.3.1` would typically not be added to Coder unless a user needs to go
-   back to a very specific image from
-
 ## Add a tag
 
 To add a tag to Coder:
@@ -92,3 +40,53 @@ To use an existing tag as the default tag, click the **vertical ellipses** for a
 tag and select **Make default**.
 
 ![Set Existing Tag as Default](../assets/existing-tag-as-default.png)
+
+## Image tag lifecycle
+
+Coder uses image tags to determine which image variant on which the user wants
+to base their environment.
+
+Image tags are expressed using the following notation:
+
+```text
+<image>:<image-tag>
+```
+
+Examples include:
+
+```text
+ubuntu:20.04
+ubuntu:rolling
+codercom/enterprise-node:ubuntu
+mycorp/myproject:v1
+```
+
+The name formatting of the tag will change the way Coder behaves regarding image
+updates:
+
+- If you build your environment using a `ubuntu:rolling` or `ubuntu:latest` tag,
+  Coder prompts you to rebuild for patches, security updates, and major version
+  releases. If you're supporting a SaaS product or working on mobile apps, you
+  may opt for this to ensure that your tools stay up-to-date.
+
+- If you build your environment using a specific version tag (e.g.,
+  `ubuntu:20.04`), Coder will alert you regarding patches and security updates
+  so that you rebuild your environment (you won't get these fixes otherwise).
+  Coder does not, however, alert you regarding minor releases (e.g., movement
+  from `20.04` to `20.10`). This is a good option for those offering long-term
+  support of software with lengthier version cycles or those supporting multiple
+  versions where you expect to revert back to a prior release to investigate and
+  fix issues.
+
+- If you build your environment using a tag like
+  `codercom/enterprise-node:ubuntu`, the image name indicates the company and
+  software architecture (also known as the node), while the tag specifies the
+  base image. Without any additional information, such as a version number, you
+  can expect this to operate like a `rolling` or `latest` tag. You can also
+  assume there are other variants, such as `codercom/enterprise-node:centos` or
+  `codercom/enterprise-node:arch`.
+
+- If you build your environment using `mycorp/myproject:v1`, the image is
+  associated with a specific project's major version. You can apply the `:v1`
+  tag to the most recent build for the image, while you can use `:v1.3` or
+  `:v1.3.1` to pull a more specific tag version.
