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 diff --git a/docs/.style/styles/Coder/README.md b/docs/.style/styles/Coder/README.md index 4023b22f53bbc..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`. -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" +- Limit `we` - Setup vs set up, Quickstart casing - Next steps vs Learn more - Vale substitution rule scaffold @@ -28,9 +28,8 @@ incrementally. Planned starter rules: - 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 4040ec32549e6..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 b35f105dd08e8..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 3511601761b6a..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 138bfdbb98dce..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/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..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: