Use semver module in README.md

README.md

@@ -2,6 +2,29 @@
 
 Terraform modules for working with cloud.gov commonly used by [18f/rails-template](https://github.com/18f/rails-template) based apps
 
+## Usage
+
+Specify acceptable versions of these modules using an [NPM-style version constraint](https://github.com/npm/node-semver#versions), using our [semver module](./semver). ([Terraform doesn't support version constraints for github-hosted modules](https://developer.hashicorp.com/terraform/language/modules/sources#github).) 
+
+```terraform
+# Specify a (NPM-style) version constraint for the modules you use
+locals {
+  module_versions = {
+    database = "^0.x", # major version 0
+    s3       = "^0.x"  # major version 0
+  }
+}
+
+# Find the most recent versions matching those constraints...
+module "version" {
+  for_each           = local.module_versions
+  source             = "github.com/18f/terraform-cloudgov//semver"
+  version_constraint = each.value
+}
+
+# ...then refer to the source for those modules using the calculated versions, as demonstrated below
+```
+
 ## Module Examples
 
 ### database
@@ -10,7 +33,7 @@ Creates an RDS database based on the `rds_plan_name` variable and outputs the `i
 
 ```
 module "database" {
-  source = "github.com/18f/terraform-cloudgov//database?ref=v0.6.0"
+  source = "github.com/18f/terraform-cloudgov//database?ref=v${module.version["database"].target_version}"
 
   cf_org_name      = local.cf_org_name
   cf_space_name    = local.cf_space_name
@@ -25,7 +48,7 @@ Creates a Elasticache redis instance and outputs the `instance_id` for use elsew
 
 ```
 module "redis" {
-  source = "github.com/18f/terraform-cloudgov//redis?ref=v0.6.0"
+  source = "github.com/18f/terraform-cloudgov//redis?ref=v${module.version["redis"].target_version}"
 
   cf_org_name      = local.cf_org_name
   cf_space_name    = local.cf_space_name
@@ -40,7 +63,7 @@ Creates an s3 bucket and outputs the `bucket_id` for use elsewhere.
 
 ```
 module "s3" {
-  source = "github.com/18f/terraform-cloudgov//s3?ref=v0.6.0"
+  source = "github.com/18f/terraform-cloudgov//s3?ref=v${module.version["s3"].target_version}"
 
   cf_org_name      = local.cf_org_name
   cf_space_name    = local.cf_space_name
@@ -58,7 +81,7 @@ Note that the domain must be created in cloud.gov by an OrgManager before this m
 
 ```
 module "domain" {
-  source = "github.com/18f/terraform-cloudgov//domain?ref=v0.7.0"
+  source = "github.com/18f/terraform-cloudgov//domain?ref=v${module.version["domain"].target_version}"
 
   cf_org_name      = local.cf_org_name
   cf_space_name    = local.cf_space_name
@@ -79,7 +102,7 @@ Notes:
 
 ```
 module "clamav" {
-  source = "github.com/18f/terraform-cloudgov//clamav?ref=v0.6.0"
+  source = "github.com/18f/terraform-cloudgov//clamav?ref=v${module.version["clamav"].target_version}"
 
   cf_org_name    = local.cf_org_name
   cf_space_name  = local.cf_space_name
@@ -102,7 +125,7 @@ Creates a new cloud.gov space, such as when creating an egress space, and output
 
 ```
 module "egress_space" {
-  source = "github.com/18f/terraform-cloudgov//cg_space?ref=v0.6.0"
+  source = "github.com/18f/terraform-cloudgov//cg_space?ref=v${module.version["cg_space"].target_version}"
 
   cf_org_name   = local.cf_org_name
   cf_space_name = "${local.cf_space_name}-egress"
@@ -117,7 +140,3 @@ module "egress_space" {
   ]
 }
 ```
-
-## Staying up to date
-
-Note that [Terraform doesn't support version constraints for github module sources](https://developer.hashicorp.com/terraform/language/modules/sources#github). To use the latest available versions of these modules using a version constraint, use our [semver module](./semver). 

semver/README.md

@@ -8,8 +8,8 @@ Find a tag for this repository matching NPM-style version constraints
 # Specify a version constraint for each module we plan to use
 locals {
   module_versions = {
-    database = ">0.5.0",
-    s3       = ">0.6.0"
+    database = "^0.x", # major version 0
+    s3       = "^0.x"  # major version 0
   }
 }
 
@@ -32,4 +32,3 @@ module "s3" {
   # [...]
 }
 ```
-

semver/tests/default/default.tf

@@ -13,7 +13,10 @@ terraform {
 # Fixture constraints
 locals {
   module_versions = {
-    greaterthan = ">0.5.0",
+    # This test will break after we tag something higher than 1.0.0; fix and
+    # expand these tests then!
+    # https://github.com/npm/node-semver#tilde-ranges-123-12-1
+    greaterthan = "~0", 
   }
 
   latest_tag = trimprefix(jsondecode(data.http.latest_version.response_body).tag_name, "v")
@@ -39,7 +42,6 @@ resource "test_assertions" "greater-than-is-latest" {
   equal "target_version" {
     description = "greater than should always be the latest in the repo"
     got  = module.version["greaterthan"].target_version
-    # want = "0.7.0" # Need to programmatically derive this
     want = local.latest_tag
   }
 }