Merge pull request #278 from bitovi/enh/versioning

Document the stabilized BitOps versioning in the docs
bitovi · Aug 17, 2022 · 07b5c1c · 07b5c1c
2 parents 62374e9 + 50e358b
commit 07b5c1c
Show file tree

Hide file tree

Showing 5 changed files with 37 additions and 5 deletions.
diff --git a/docs/about.md b/docs/about.md
@@ -4,12 +4,12 @@
 
 We welcome any contributions or suggestions from the community with open arms. Take a look at our [Contributing](contributing.md) guide.
 
-Come hang out with us on [Slack](https://www.bitovi.com/community/slack)!
+Come hang out with us on [Slack](https://www.bitovi.com/community/slack) `#bitops` channel!
 
 ## Release History
 
 See [Releases](https://github.com/bitovi/bitops/releases).
 
 ## License
 
-[MIT License](license.md).
+[MIT License](license.md).
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -34,6 +34,7 @@ docker pull bitovi/bitops
 cd $YOUR_OPERATIONS_REPO
 docker run bitovi/bitops -v $(pwd):/opt/bitops_deployment
 ```
+If you need specific version of BitOps, please check the [BitOps versioning](versioning.md).
 
 ## Supported Tools
 * [Provision infrastructure with CloudFormation](tool-configuration/configuration-cloudformation.md)

diff --git a/docs/migration/2.0.0-migration.md → docs/migration/2.0-migration.md b/docs/migration/2.0.0-migration.md → docs/migration/2.0-migration.md
@@ -1,3 +1,5 @@
+Here is the list of major breaking changes that you need to be aware of when migrating from BitOps `v1.0` to `v2.0`.
+
 # Bitops Core
 
 ## Environment Variables

diff --git a/docs/versioning.md b/docs/versioning.md
@@ -0,0 +1,28 @@
+# Versioning
+BitOps Docker images are packaged and hosted on [Docker Hub](https://hub.docker.com/r/bitovi/bitops).
+Here is how these images are named, versioned and tagged.
+
+* An image with a version tag containing a [semver](https://semver.org) (e.g. `2.0.0`) is immutable and refers to the [stable release](https://github.com/bitovi/bitops/releases).
+* A version tag equal to `latest` is always mutable and points to the latest [stable release](https://github.com/bitovi/bitops/releases).
+* A version tag containing `dev` is always mutable and refers to the current development state in the [`main`](https://github.com/bitovi/bitops/tree/main) repository branch.
+* A version tag containing `omnibus` points to the default image that includes recommended devops tools.
+* A version tag containing `base` refers to minimal image with no other tools. You can build a [custom BitOps image](plugins.md) from it.
+
+## Official Images
+To clear up any potential confusion regarding the versioning of the [`bitovi/bitops`](https://hub.docker.com/r/bitovi/bitops) image, we use the following table.
+
+| Image Name | PreInstalled Tools| Docker image name | Supported Cloud provider | Additional stable image tags | Development image tags (`main` branch) |
+|-|-|-|-|-|-|
+| omnibus | Terraform <br/> Cloudformation <br/> Ansible <br/> Helm <br/> Kubectl <br/> AWS CLI| `bitovi/bitops:2.0.0-omnibus` | AWS | `latest` <br/> `2.0.0` | `dev` |
+| | | | | | | | 
+| aws-terraform | Terraform <br/> AWS CLI | `bitovi/bitops:2.0.0-aws-terraform` | AWS | | |
+| aws-ansible   | Ansible <br/> AWS CLI | `bitovi/bitops:2.0.0-aws-ansible` | AWS | | | 
+| aws-helm      | Helm <br/> Terraform <br/> AWS CLI | `bitovi/bitops:2.0.0-aws-helm` | AWS | | |
+| | | | | | |
+| base | BitOps source | `bitovi/bitops:2.0.0-base` | - | `base` | `dev-base` |
+
+## Version Pinning
+* We always recommend pinning the stable version of BitOps to avoid any breaking changes like `bitovi/bitops:2.0.0`.
+* If the security is higher priority for you, use sha256 digest like `bitovi/bitops:sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3`.
+
+See more in the [docker documentation](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -27,17 +27,18 @@ nav:
   - Operations Repository: operations-repo-structure.md
   - Configuration:
     - Base Configuration: configuration-base.md
-    - Cloud Configuration: 
+    - Cloud Configuration:
       - AWS: cloud-configuration/configuration-aws.md
-    - Tool Configuration: 
+    - Tool Configuration:
       - Terraform: tool-configuration/configuration-terraform.md
       - Ansible: tool-configuration/configuration-ansible.md
       - Helm: tool-configuration/configuration-helm.md
       - Cloudformation: tool-configuration/configuration-cloudformation.md
     - Default Environment: default-environment.md
+    - BitOps Versioning: versioning.md
   - Examples: examples.md
   - Upgrade:
-    - 2.0.0: migration/2.0.0-migration.md
+    - 2.0: migration/2.0-migration.md
   - Development:
     - Local development: development-local.md
     - Custom Images: custom-image.md