From 8985caed20198728eda42102efe636a0a92a0a02 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Tue, 19 May 2026 19:24:43 +0000 Subject: [PATCH 1/4] docs: fix HashiCorp casing in prose and sidebar Five Markdown files used "Hashicorp" instead of "HashiCorp"; the docs/manifest.json sidebar entry for the Vault integration page also carried "Hashicorp" in title and description. HashiCorp's brand uses mixed case (capital H, capital C); the URLs and the Terraform provider addresses (e.g. hashicorp/vault) stay lowercase by convention. This commit fixes the prose-only instances and the sidebar entry so the Coder.BrandNames Vale rule landing in the next commit lints a clean corpus. Path on docs/admin/integrations/vault.md is unchanged; the sidebar title change does not affect the page URL on coder.com. --- docs/admin/integrations/multiple-kube-clusters.md | 2 +- docs/admin/integrations/opentofu.md | 2 +- docs/admin/templates/extending-templates/workspace-tags.md | 2 +- docs/admin/templates/index.md | 2 +- docs/manifest.json | 4 ++-- docs/tutorials/template-from-scratch.md | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/admin/integrations/multiple-kube-clusters.md b/docs/admin/integrations/multiple-kube-clusters.md index 4040ec32549e6..a8826d6d1621b 100644 --- a/docs/admin/integrations/multiple-kube-clusters.md +++ b/docs/admin/integrations/multiple-kube-clusters.md @@ -95,7 +95,7 @@ tokens. Coder can store these secrets on your behalf with [managed Terraform variables](../templates/extending-templates/variables.md). Alternatively, these could also be fetched from Kubernetes secrets or even -[Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret). +[HashiCorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret). This guide assumes you have a `coder-workspaces` namespace on your remote cluster. Change the namespace accordingly. diff --git a/docs/admin/integrations/opentofu.md b/docs/admin/integrations/opentofu.md index b35f105dd08e8..d6126666214f7 100644 --- a/docs/admin/integrations/opentofu.md +++ b/docs/admin/integrations/opentofu.md @@ -11,7 +11,7 @@ Coder deployments support any custom Terraform binary, including [OpenTofu](https://opentofu.org/docs/) - an open source alternative to Terraform. -You can read more about OpenTofu and Hashicorp's licensing in our +You can read more about OpenTofu and HashiCorp's licensing in our [blog post](https://coder.com/blog/hashicorp-license) on the Terraform licensing changes. ## Using a custom Terraform binary diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md index 3511601761b6a..36c55af4a3d3f 100644 --- a/docs/admin/templates/extending-templates/workspace-tags.md +++ b/docs/admin/templates/extending-templates/workspace-tags.md @@ -109,7 +109,7 @@ Passing template tags in from other data sources or resources is not permitted. When importing the template version with `coder_workspace_tags`, the Coder provisioner server extracts raw partial queries for each workspace tag and stores them in the database. During workspace build time, the Coder server uses -the [Hashicorp HCL library](https://github.com/hashicorp/hcl) to evaluate these +the [HashiCorp HCL library](https://github.com/hashicorp/hcl) to evaluate these raw queries on-the-fly without processing the entire Terraform template. This evaluation is simpler but also limited in terms of available functions, variables, and references to other resources. diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index 138bfdbb98dce..3c02cd343fe2c 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.md @@ -15,7 +15,7 @@ Coder-specific concepts behind templates. The best way to learn the concepts is by [creating a basic template from scratch](../../tutorials/template-from-scratch.md). If you are unfamiliar with Terraform, see -[Hashicorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for +[HashiCorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for common cloud providers. ## Starter templates diff --git a/docs/manifest.json b/docs/manifest.json index 01bb9155a8fd2..aaac8102d3549 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -808,8 +808,8 @@ "path": "./admin/integrations/dx-data-cloud.md" }, { - "title": "Hashicorp Vault", - "description": "Integrate Coder with Hashicorp Vault", + "title": "HashiCorp Vault", + "description": "Integrate Coder with HashiCorp Vault", "path": "./admin/integrations/vault.md" }, { diff --git a/docs/tutorials/template-from-scratch.md b/docs/tutorials/template-from-scratch.md index 3abfdbf940c10..c29d3a9dda60b 100644 --- a/docs/tutorials/template-from-scratch.md +++ b/docs/tutorials/template-from-scratch.md @@ -22,7 +22,7 @@ server essentially runs a `terraform apply` every time a workspace is created, started, or stopped. > [!TIP] -> Haven't written Terraform before? Check out Hashicorp's +> Haven't written Terraform before? Check out HashiCorp's > [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials). Here's a simplified diagram that shows the main parts of the template we'll From 0d41b53be0f026cd9142ba5469c2226d919fcc34 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Tue, 19 May 2026 19:32:09 +0000 Subject: [PATCH 2/4] feat(docs/.style/styles/Coder): add Coder.BrandNames Vale rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First concrete rule under the Coder style. Lands as a bundled substitution rule that will hold every brand whose owner publishes a canonical casing; HashiCorp is the first entry, with GitHub, OpenTofu, Kubernetes, Terraform, JetBrains, and VS Code following under DOCS-188. Rule design: - extends: substitution, level: error. The brand owner spells it HashiCorp; any other casing in prose is wrong, not a judgment call. Vale's substitution rule type skips inline code, fenced code blocks, and URLs by default, so hashicorp/kubernetes (Terraform provider source) and developer.hashicorp.com stay untouched. - ignorecase: false and nonword: false. The wrong cases we want to flag are spelled Hashicorp (capital H, lowercase c) or HASHICORP; lowercase hashicorp in prose is fine since the corpus only uses it in URL paths. - The cleanup committed first (d71156c447) drove the existing-content violation count to zero, so the rule can ship at error from day one. Style guide entry: - A new ## Word choice → ### Brand names section in style-guide.md documents the policy, lists HashiCorp as the first enforced brand, and references DOCS-188 for the rollup. - The "Active rule set" bullet for the Coder style is updated to note that Coder.BrandNames is live (no longer "empty in v1"). Verification: - make lint/prose: 391 errors / 5201 warnings / 7681 suggestions across 458 files. Baseline error count unchanged from before the rule landed; the cleanup commit drove the would-be 7 new errors to zero. Suggestions increased by 8 (new prose triggers Google.Contractions, Google.Acronyms, etc., all expected). - make lint/markdown: 0 errors across 463 files. Closes DOCS-34. --- docs/.style/styles/Coder/BrandNames.yml | 28 +++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/.style/styles/Coder/BrandNames.yml diff --git a/docs/.style/styles/Coder/BrandNames.yml b/docs/.style/styles/Coder/BrandNames.yml new file mode 100644 index 0000000000000..a5a73f61bbad2 --- /dev/null +++ b/docs/.style/styles/Coder/BrandNames.yml @@ -0,0 +1,28 @@ +# Coder.BrandNames - enforce canonical brand-name casing in prose. +# +# Vale's substitution rule applies in prose only; it skips fenced code +# blocks, inline code, and URLs by default. That means `hashicorp/kubernetes` +# (Terraform provider source) and `developer.hashicorp.com` (URL) stay +# untouched. The rule fires on body text and headings where the wrong +# casing appears as a normal word. +# +# Level: error. Each swap targets a brand whose owner publishes a +# canonical casing; "Hashicorp Vault" instead of "HashiCorp Vault" is +# objectively wrong, not a judgment call. The existing-content violation +# count is zero (cleanup landed in the previous commit), so this rule +# can ship at error from day one. +# +# Adding a brand: append a key/value to the swap table below and audit +# the docs corpus for the wrong-casing variant. Keep the message template +# unchanged; the `%s` token interpolates the matched (wrong) text. +extends: substitution +message: "Use '%s' instead of '%s' (brand-name casing)." +link: https://github.com/coder/coder/blob/main/docs/.style/style-guide.md#brand-names +level: error +ignorecase: false +nonword: false +action: + name: replace +swap: + Hashicorp: HashiCorp + HASHICORP: HashiCorp From 631094bfdbb5bb06c9d27dde213ee2112fa7ffa3 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 18:24:47 +0000 Subject: [PATCH 3/4] docs(.style/styles/Coder/README.md): scrub planned-rules notes obsoleted by Coder.BrandNames The previous commit ("feat(docs/.style/styles/Coder): add Coder.BrandNames Vale rule") ships the first concrete rule under this directory, which obsoletes two claims in the local README: 1. "This directory is intentionally empty for now" no longer holds; BrandNames.yml ships in this PR. 2. The "HashiCorp casing" bullet under planned starter rules is now implemented and documented in docs/.style/style-guide.md under "### Brand names". Rewrite the lead-in to point readers at the YAML files in the directory and at the style-guide.md sections for the user-facing policy each rule enforces. Drop the HashiCorp casing bullet. The remaining planned-coverage entries stay so the README still serves as the rule-authoring landing page. --- docs/.style/styles/Coder/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/.style/styles/Coder/README.md b/docs/.style/styles/Coder/README.md index 4023b22f53bbc..5105691194202 100644 --- a/docs/.style/styles/Coder/README.md +++ b/docs/.style/styles/Coder/README.md @@ -4,11 +4,11 @@ Custom Vale rules specific to Coder live here. Each rule is a YAML file that Vale loads through the `BasedOnStyles = Coder` setting in the repo-root `.vale.ini`. -This directory is intentionally empty for now. Follow-up PRs add rules -incrementally. Planned starter rules: +Active rules ship as YAML files in this directory; see the matching +sections in `docs/.style/style-guide.md` for the user-facing policy each +rule enforces. Follow-up PRs add rules incrementally. Planned coverage: - Dev Container terminology -- HashiCorp casing - Limit "we" - Setup vs set up, Quickstart casing - Next steps vs Learn more From 18dca80173dbb424399de23ba9f0a73b874da124 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 19:21:23 +0000 Subject: [PATCH 4/4] docs: apply semantic line breaks and fix Vale findings on PR-touched files Pre-review pass on every Markdown file this PR modified. Style-guide infrastructure (docs/.style/style-guide.md, docs/.style/styles/Coder/README.md) gets the full treatment: convert every paragraph and list to semantic line breaks per sembr.org (one sentence per line, with optional breaks at major clause boundaries); fix Google.Will, Google.We, Google.Contractions, Google.Passive, and Google.WordList warnings where the rewrite preserves the original meaning. Replace 'To be filled in by follow-up PRs. Planned coverage:' with 'Coming in follow-up PRs:' (active voice, no 'will'). Wrap the literal 'we' mention in backticks so the meta-discussion does not trip Google.We. The five product docs touched only by the HashiCorp casing swap get sembr applied to the swap paragraph only, per scoping discussion with @nickvigilante: multiple-kube-clusters.md, opentofu.md, workspace-tags.md, templates/index.md, template-from-scratch.md. Pre-existing Vale findings on those product docs (passive voice, weasel words, parens, etc.) stay in place; cleanup belongs in a separate sembr/Vale rollout ticket. --- docs/.style/styles/Coder/README.md | 19 +++++++++---------- .../integrations/multiple-kube-clusters.md | 3 +-- docs/admin/integrations/opentofu.md | 3 +-- .../extending-templates/workspace-tags.md | 10 +++------- docs/admin/templates/index.md | 10 +++------- docs/tutorials/template-from-scratch.md | 4 ++-- 6 files changed, 19 insertions(+), 30 deletions(-) diff --git a/docs/.style/styles/Coder/README.md b/docs/.style/styles/Coder/README.md index 5105691194202..05d50605b4b85 100644 --- a/docs/.style/styles/Coder/README.md +++ b/docs/.style/styles/Coder/README.md @@ -1,15 +1,15 @@ # Coder custom Vale rules -Custom Vale rules specific to Coder live here. Each rule is a YAML file -that Vale loads through the `BasedOnStyles = Coder` setting in the -repo-root `.vale.ini`. +Custom Vale rules specific to Coder live here. +Each rule is a YAML file that Vale loads through the `BasedOnStyles = Coder` setting in the repo-root `.vale.ini`. -Active rules ship as YAML files in this directory; see the matching -sections in `docs/.style/style-guide.md` for the user-facing policy each -rule enforces. Follow-up PRs add rules incrementally. Planned coverage: +Active rules ship as YAML files in this directory. +See the matching sections in `docs/.style/style-guide.md` for the user-facing policy each rule enforces. +Follow-up PRs add rules incrementally. +Planned coverage: - Dev Container terminology -- Limit "we" +- Limit `we` - Setup vs set up, Quickstart casing - Next steps vs Learn more - Vale substitution rule scaffold @@ -28,9 +28,8 @@ rule enforces. Follow-up PRs add rules incrementally. Planned coverage: - The rule is objectively correct (typo, brand-name casing, banned substitution). - The existing-content violation count for the rule reaches zero. -4. A follow-up PR will add a parity CI check that verifies every rule - here has a matching section in `style-guide.md`. Add the section in - the same PR as the rule. +4. A follow-up PR adds a parity CI check that verifies every rule here has a matching section in `style-guide.md`. + Add the section in the same PR as the rule. ## Reference diff --git a/docs/admin/integrations/multiple-kube-clusters.md b/docs/admin/integrations/multiple-kube-clusters.md index a8826d6d1621b..32d5ced73bbfc 100644 --- a/docs/admin/integrations/multiple-kube-clusters.md +++ b/docs/admin/integrations/multiple-kube-clusters.md @@ -94,8 +94,7 @@ Alternatively, you can authenticate with remote clusters with ServiceAccount tokens. Coder can store these secrets on your behalf with [managed Terraform variables](../templates/extending-templates/variables.md). -Alternatively, these could also be fetched from Kubernetes secrets or even -[HashiCorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret). +Alternatively, these could also be fetched from Kubernetes secrets or even [HashiCorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret). This guide assumes you have a `coder-workspaces` namespace on your remote cluster. Change the namespace accordingly. diff --git a/docs/admin/integrations/opentofu.md b/docs/admin/integrations/opentofu.md index d6126666214f7..b078f16af4951 100644 --- a/docs/admin/integrations/opentofu.md +++ b/docs/admin/integrations/opentofu.md @@ -11,8 +11,7 @@ Coder deployments support any custom Terraform binary, including [OpenTofu](https://opentofu.org/docs/) - an open source alternative to Terraform. -You can read more about OpenTofu and HashiCorp's licensing in our -[blog post](https://coder.com/blog/hashicorp-license) on the Terraform licensing changes. +You can read more about OpenTofu and HashiCorp's licensing in our [blog post](https://coder.com/blog/hashicorp-license) on the Terraform licensing changes. ## Using a custom Terraform binary diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md index 36c55af4a3d3f..f2c5ac874cbe1 100644 --- a/docs/admin/templates/extending-templates/workspace-tags.md +++ b/docs/admin/templates/extending-templates/workspace-tags.md @@ -106,13 +106,9 @@ Passing template tags in from other data sources or resources is not permitted. ### HCL syntax -When importing the template version with `coder_workspace_tags`, the Coder -provisioner server extracts raw partial queries for each workspace tag and -stores them in the database. During workspace build time, the Coder server uses -the [HashiCorp HCL library](https://github.com/hashicorp/hcl) to evaluate these -raw queries on-the-fly without processing the entire Terraform template. This -evaluation is simpler but also limited in terms of available functions, -variables, and references to other resources. +When importing the template version with `coder_workspace_tags`, the Coder provisioner server extracts raw partial queries for each workspace tag and stores them in the database. +During workspace build time, the Coder server uses the [HashiCorp HCL library](https://github.com/hashicorp/hcl) to evaluate these raw queries on-the-fly without processing the entire Terraform template. +This evaluation is simpler but also limited in terms of available functions, variables, and references to other resources. #### Supported syntax diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index 3c02cd343fe2c..20c47f88a15d4 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.md @@ -10,13 +10,9 @@ underlying infrastructure that all Coder workspaces run on. ## Learn the concepts -While templates are written in standard Terraform, it's important to learn the -Coder-specific concepts behind templates. The best way to learn the concepts is -by -[creating a basic template from scratch](../../tutorials/template-from-scratch.md). -If you are unfamiliar with Terraform, see -[HashiCorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for -common cloud providers. +While templates are written in standard Terraform, it's important to learn the Coder-specific concepts behind templates. +The best way to learn the concepts is by [creating a basic template from scratch](../../tutorials/template-from-scratch.md). +If you are unfamiliar with Terraform, see [HashiCorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for common cloud providers. ## Starter templates diff --git a/docs/tutorials/template-from-scratch.md b/docs/tutorials/template-from-scratch.md index c29d3a9dda60b..11ab141ff6e73 100644 --- a/docs/tutorials/template-from-scratch.md +++ b/docs/tutorials/template-from-scratch.md @@ -22,8 +22,8 @@ server essentially runs a `terraform apply` every time a workspace is created, started, or stopped. > [!TIP] -> Haven't written Terraform before? Check out HashiCorp's -> [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials). +> Haven't written Terraform before? +> Check out HashiCorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials). Here's a simplified diagram that shows the main parts of the template we'll create: