From 1c568e2dd579d8efd538b033ef8fd8bf727a4313 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Tue, 19 May 2026 19:24:43 +0000 Subject: [PATCH 1/5] 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 8504b4fa1074a..4b2c24bc7c8f8 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 9b1b787323d63bd388cca38a01307935e8eaa7df Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Tue, 19 May 2026 19:32:09 +0000 Subject: [PATCH 2/5] 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/style-guide.md | 19 ++++++++++++++++- docs/.style/styles/Coder/BrandNames.yml | 28 +++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 docs/.style/styles/Coder/BrandNames.yml diff --git a/docs/.style/style-guide.md b/docs/.style/style-guide.md index 1065287a86863..8ec0a6f3efd99 100644 --- a/docs/.style/style-guide.md +++ b/docs/.style/style-guide.md @@ -40,12 +40,29 @@ To be filled in by follow-up PRs. Planned coverage: To be filled in by follow-up PRs. Planned coverage: - Inclusive-language substitutions -- HashiCorp casing - Dev Container terminology - "Setup" vs "set up" and Quickstart casing - "Next steps" vs "Learn more" - Weasel words +### Brand names + +Use each brand's canonical casing in prose. URLs and code references +(Terraform provider source addresses, GitHub paths) keep the lowercase +form their owner uses; Vale's `substitution` rule skips inline code and +links by default, so those are not affected. + +| Wrong | Correct | Notes | +|-------------|-------------|-----------------------------------| +| `Hashicorp` | `HashiCorp` | Mixed case: capital H, capital C. | + +More brands (GitHub, OpenTofu, Kubernetes, Terraform, JetBrains, VS +Code) extend this table as they land in follow-up PRs. + +Enforced by `Coder.BrandNames` (level `error`). To add a brand: append a +swap to `docs/.style/styles/Coder/BrandNames.yml`, run `make lint/prose` +to catch existing-content violations, fix them, then commit. + ## Capitalization and punctuation To be filled in by follow-up PRs. Planned coverage: 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 d40e6814b94317d88ce1dc72b1f82e2254ce82ab Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 18:24:47 +0000 Subject: [PATCH 3/5] 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 2a70166eeb7b1..a74aef8b3af34 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 35833b6bc17f1a582d45984b06de2af4d46c67f4 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 19:21:23 +0000 Subject: [PATCH 4/5] 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/style-guide.md | 88 ++++++++----------- docs/.style/styles/Coder/README.md | 34 ++++--- .../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 +- 7 files changed, 63 insertions(+), 89 deletions(-) diff --git a/docs/.style/style-guide.md b/docs/.style/style-guide.md index 8ec0a6f3efd99..e7b141d516596 100644 --- a/docs/.style/style-guide.md +++ b/docs/.style/style-guide.md @@ -1,43 +1,38 @@ # Coder documentation style guide -This is the canonical style guide for the Coder documentation. It is the -source of truth that the Vale rules in `docs/.style/styles/Coder/` enforce. +This is the canonical style guide for the Coder documentation. +It's the source of truth that the Vale rules in `docs/.style/styles/Coder/` enforce. -Status: scaffold. Sections below are populated by follow-up PRs; this -page starts as a table of contents and grows as those PRs land. +Status: scaffold. +Follow-up PRs populate the sections below. +This page starts as a table of contents and grows as those PRs land. ## How to use this guide -This page is a scaffold while follow-up PRs land. Sections marked "To be -filled in" are placeholders. For anything not yet covered, see the -public summary at -[`docs/about/contributing/documentation.md`](../about/contributing/documentation.md). +This page is a scaffold while follow-up PRs land. +Sections marked "Coming in follow-up PRs" are placeholders. +For anything not yet covered, see the public summary at [`docs/about/contributing/documentation.md`](../about/contributing/documentation.md). - **Contributors**: read the section that matches what you are writing. - Each rule notes the Vale rule ID, if any, so you can reproduce the - warning locally. -- **Reviewers**: cite the section in a review comment. Reviews are easier - when the guidance is in one place. -- **AI agents**: read this page in full before editing anything under - `docs/`. The Coder Agents and Claude Code guides - ([`AGENTS.md`](../../AGENTS.md), - [`.claude/docs/DOCS_STYLE_GUIDE.md`](../../.claude/docs/DOCS_STYLE_GUIDE.md)) - link here. + Each rule notes the Vale rule ID, if any, so you can reproduce the warning locally. +- **Reviewers**: cite the section in a review comment. + Reviews are easier when the guidance is in one place. +- **AI agents**: read this page in full before editing anything under `docs/`. + The Coder Agents and Claude Code guides ([`AGENTS.md`](../../AGENTS.md), [`.claude/docs/DOCS_STYLE_GUIDE.md`](../../.claude/docs/DOCS_STYLE_GUIDE.md)) link here. ## Voice and tone -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Active voice - Second person - Plural nouns and pronouns where number is uncertain -- Product voice (`stop` over `kill`, `turn off` over `disable` in - user-facing copy) -- Limiting "we" +- Product voice (`stop` over `kill`, `turn off` over `disable` in user-facing copy) +- Limit `we` ## Word choice -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Inclusive-language substitutions - Dev Container terminology @@ -47,25 +42,24 @@ To be filled in by follow-up PRs. Planned coverage: ### Brand names -Use each brand's canonical casing in prose. URLs and code references -(Terraform provider source addresses, GitHub paths) keep the lowercase -form their owner uses; Vale's `substitution` rule skips inline code and -links by default, so those are not affected. +Use each brand's canonical casing in prose. +URLs and code references (Terraform provider source addresses, GitHub paths) keep the lowercase form their owner uses. +Vale's `substitution` rule skips inline code and links by default, so those aren't affected. | Wrong | Correct | Notes | |-------------|-------------|-----------------------------------| | `Hashicorp` | `HashiCorp` | Mixed case: capital H, capital C. | -More brands (GitHub, OpenTofu, Kubernetes, Terraform, JetBrains, VS -Code) extend this table as they land in follow-up PRs. +More brands (GitHub, OpenTofu, Kubernetes, Terraform, JetBrains, VS Code) extend this table as they land in follow-up PRs. -Enforced by `Coder.BrandNames` (level `error`). To add a brand: append a -swap to `docs/.style/styles/Coder/BrandNames.yml`, run `make lint/prose` -to catch existing-content violations, fix them, then commit. +Enforced by `Coder.BrandNames` (level `error`). +To add a brand: append a swap to `docs/.style/styles/Coder/BrandNames.yml`, +run `make lint/prose` to catch existing-content violations, +fix them, then commit. ## Capitalization and punctuation -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Sentence case in titles and headings - General capitalization policy @@ -73,46 +67,40 @@ To be filled in by follow-up PRs. Planned coverage: ## Formatting -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Bold for UI elements - Italics for parameter names and version variables -- Code font for user input, command-line utility names, filenames, - environment variables, HTTP verbs and status codes, placeholder - variables +- Code font for user input, command-line utility names, filenames, environment variables, HTTP verbs and status codes, placeholder variables - Code blocks with explicit language fences ## Vale enforcement -The repo-root `.vale.ini` configures Vale to read styles from -`docs/.style/styles/`. The starter configuration combines: +The repo-root `.vale.ini` configures Vale to read styles from `docs/.style/styles/`. +The starter configuration combines: - Google's developer-docs base style - A curated subset of `alex` (inclusive-language) - A curated subset of `write-good` (wordiness) - Coder-specific custom rules in `docs/.style/styles/Coder/` -The rationale for the cherry-picked base styles and the severity -policy lives in `.vale.ini`'s inline comments. Run `make lint/prose` -to reproduce the baseline locally. +The rationale for the cherry-picked base styles and the severity policy lives in `.vale.ini`'s inline comments. +Run `make lint/prose` to reproduce the baseline locally. ## Editor setup -To be filled in by a follow-up PR. Will cover VS Code, Cursor, -JetBrains, and Neovim. +A follow-up PR adds coverage for VS Code, Cursor, JetBrains, and Neovim. ## Relationship to `docs/about/contributing/documentation.md` -A public-facing prose summary lives today at -[`docs/about/contributing/documentation.md`](../about/contributing/documentation.md). -A follow-up PR will redirect that page to this guide; until then, -follow the public summary for anything the scaffolded sections above do -not yet cover. New prose rules land here; the public page is frozen -pending the redirect. +A public-facing prose summary lives today at [`docs/about/contributing/documentation.md`](../about/contributing/documentation.md). +A follow-up PR redirects that page to this guide. +Until then, follow the public summary for anything the scaffolded sections in this guide don't yet cover. +New prose rules land here; the public page is frozen pending the redirect. ## Third-party references -When this guide does not cover something, consult: +When this guide doesn't cover something, consult: | Type of guidance | Reference | |---------------------|-----------------------------------------------------------------------------------------| diff --git a/docs/.style/styles/Coder/README.md b/docs/.style/styles/Coder/README.md index a74aef8b3af34..8602a8330f24e 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 @@ -20,19 +20,15 @@ rule enforces. Follow-up PRs add rules incrementally. Planned coverage: ## Authoring a new rule -1. Write a YAML file under this directory. Name it after the rule's - intent, for example `InclusiveLanguage.yml` or `ProductVoice.yml`. -2. Each rule's `message:` should link to the matching section in - `docs/.style/style-guide.md`, ideally with a deep-link anchor, so a - contributor reading a Vale warning can jump straight to the guidance. -3. Land at `level: warning` first. Promote to `level: error` only after - both conditions hold: - - The rule is objectively correct (typo, brand-name casing, banned - substitution). +1. Write a YAML file under this directory. + Name it after the rule's intent, for example `InclusiveLanguage.yml` or `ProductVoice.yml`. +2. Each rule's `message:` should link to the matching section in `docs/.style/style-guide.md`, ideally with a deep-link anchor, so a contributor reading a Vale warning can jump straight to the guidance. +3. Land at `level: warning` first. + Promote to `level: error` only after both conditions hold: + - 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: From e6c7dd080e5fb34c6265dd51618c5ac618172b82 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 20:40:18 +0000 Subject: [PATCH 5/5] feat(.vale.ini): disable Google.Parens Group with the other disabled Google rules (EmDash, Latin, Spacing). Parens are a normal English punctuation device for clarification, examples, and disambiguation; the rule fires on every use without distinguishing stylistic intent from misuse, so its signal-to-noise ratio is effectively zero even at suggestion level. Net effect on the corpus: drops ~1800 noise findings from `make lint/prose` (8042 suggestions before, 6247 after) without weakening any policy. Move Google.WordList down next to its own rationale comment now that the previous 'soften two high-volume Google rules' grouping no longer applies. --- .vale.ini | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/.vale.ini b/.vale.ini index a7a618fad12a1..2fd46db96a94f 100644 --- a/.vale.ini +++ b/.vale.ini @@ -48,10 +48,12 @@ Google.EmDash = NO # produces noise without value. Google.Latin = NO -# Soften two high-volume Google rules. The signal-to-noise ratio is low -# at the default warning level. -Google.Parens = suggestion -Google.WordList = warning +# Google.Parens flags every paren use as "use parentheses judiciously." +# Parens are a normal English punctuation device for clarification, +# examples, and disambiguation. The rule cannot distinguish stylistic +# intent from misuse, so even at suggestion level its signal-to-noise +# ratio is effectively zero. Disable. +Google.Parens = NO # Google.Spacing flags fully-qualified Go type names like # `codersdk.WorkspaceAgent` as "should have one space." It produces ~4,500 @@ -64,6 +66,11 @@ Google.WordList = warning # `error`. Google.Spacing = NO +# Google.WordList is the canonical Google word-substitution table. Keep +# at warning (the default for the Google package) so non-canonical word +# choices surface as CI annotations. +Google.WordList = warning + # --- write-good curation --------------------------------------------------- # Passive voice is contextually correct often enough that flagging every # instance teaches nothing. E-Prime forbids forms of "to be" entirely,