From 0c135980bd73deb4d4f95a8583d0d495f7c91451 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 17 Sep 2025 16:55:08 -0400 Subject: [PATCH 1/9] Add AGENTS.md file Fixes DOC-14837 See also: https://agents.md --- src/current/AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 src/current/AGENTS.md diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md new file mode 100644 index 00000000000..3f6412f6efb --- /dev/null +++ b/src/current/AGENTS.md @@ -0,0 +1,45 @@ +# AGENTS.md for CockroachDB docs + +Hello! We're working together on docs for CockroachDB, a distributed SQL database. The docs are located in Markdown files (with Liquid templates) in various subdirectories of this one. + +This file has instructions & general info for working with us on these docs. Please pay close attention to things written here. + +Docs for each released version are in subdirectories named for the version, e.g., `v25.4`. + +Docs for the Cockroach Cloud hosted version are in `cockroachcloud`. + +Docs related to release notes and other release-related matters are in `releases`. + +## Style guide + +Our style guide lives in `StyleGuide.md` in the root of this repository. Please follow the guidance there carefully when writing docs. + +## Include files + +To avoid repeating text across different files, we use shared "include files" (or just: "includes") which are referenced using the following syntax. + +For includes that are shared in many places: + +``` +{% include common/define-watched-cdc.md %} +``` + +For includes that are used in the Cloud product: + +``` +{% include cockroachcloud/metrics-time-interval-selection.md %} +``` + +For includes that are used in a specific version: + +``` +{% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %} +``` + +The includes are all located in subdirectories of the `_include` directory, i.e., + +- `_include/common` for widely shared things +- `_include/cockroachcloud` for Cloud +- `_include/v25.4` for v25.4 docs + + From afcc1bfc14ca12b70da9f0ea08dbf8a7f64b6aa1 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:50:52 -0400 Subject: [PATCH 2/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index 3f6412f6efb..5806fcc8890 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -6,7 +6,7 @@ This file has instructions & general info for working with us on these docs. Ple Docs for each released version are in subdirectories named for the version, e.g., `v25.4`. -Docs for the Cockroach Cloud hosted version are in `cockroachcloud`. +Docs specific to the CockroachDB Cloud product are in `cockroachcloud`. Docs related to release notes and other release-related matters are in `releases`. From 52703563bbbff30d2db687444b3b28affc19a279 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:51:03 -0400 Subject: [PATCH 3/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index 5806fcc8890..3c11d29e0fa 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -2,7 +2,7 @@ Hello! We're working together on docs for CockroachDB, a distributed SQL database. The docs are located in Markdown files (with Liquid templates) in various subdirectories of this one. -This file has instructions & general info for working with us on these docs. Please pay close attention to things written here. +This file has instructions and general info for working with us on these docs. Please pay close attention to things written here. Docs for each released version are in subdirectories named for the version, e.g., `v25.4`. From 1c0305dc90742ff4ac9b68a951a9c2d767b7949a Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:51:11 -0400 Subject: [PATCH 4/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index 3c11d29e0fa..35f403acba3 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -36,6 +36,8 @@ For includes that are used in a specific version: {% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %} ``` +Note: The Liquid variable `{{page.version.version}}` resolves to the major version in the path of the page where it is used (e.g. `v25.4`). References to version-specific includes often use this, allowing the same page content that's used across versions to show different versions of an include, based on the current version being rendered. For example, `{% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %}`. + The includes are all located in subdirectories of the `_include` directory, i.e., - `_include/common` for widely shared things From 54be573be040d8ecb838b41abcdf776468ed3e03 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:51:17 -0400 Subject: [PATCH 5/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index 35f403acba3..a4f5673f41e 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -30,7 +30,7 @@ For includes that are used in the Cloud product: {% include cockroachcloud/metrics-time-interval-selection.md %} ``` -For includes that are used in a specific version: +For includes that we can assume only apply to specific versions, though in some cases, their content may be identical across all versions where the file exists: ``` {% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %} From 097e3b22f8e28ba64f192e50275354e22868d7b6 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:51:24 -0400 Subject: [PATCH 6/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index a4f5673f41e..be8c055359a 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -24,7 +24,7 @@ For includes that are shared in many places: {% include common/define-watched-cdc.md %} ``` -For includes that are used in the Cloud product: +For includes that pertain to the CockroachDB Cloud product: ``` {% include cockroachcloud/metrics-time-interval-selection.md %} From c7241b9cd193553dbffec12ce6ee53ac631d0ad0 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:51:42 -0400 Subject: [PATCH 7/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index be8c055359a..40da9329205 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -18,7 +18,7 @@ Our style guide lives in `StyleGuide.md` in the root of this repository. Please To avoid repeating text across different files, we use shared "include files" (or just: "includes") which are referenced using the following syntax. -For includes that are shared in many places: +For includes that apply across versions or products: ``` {% include common/define-watched-cdc.md %} From e0747a5169a20633693ea9af994f47c26e2e6478 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:51:54 -0400 Subject: [PATCH 8/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index 40da9329205..473a8ac96dc 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -33,7 +33,7 @@ For includes that pertain to the CockroachDB Cloud product: For includes that we can assume only apply to specific versions, though in some cases, their content may be identical across all versions where the file exists: ``` -{% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %} +{% include vXX.Y/misc/cert-auth-using-x509-subject.md %} ``` Note: The Liquid variable `{{page.version.version}}` resolves to the major version in the path of the page where it is used (e.g. `v25.4`). References to version-specific includes often use this, allowing the same page content that's used across versions to show different versions of an include, based on the current version being rendered. For example, `{% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %}`. From a4a8038ac655875440beafee2b878f8b1ead2086 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 19 Sep 2025 14:52:02 -0400 Subject: [PATCH 9/9] Update src/current/AGENTS.md Co-authored-by: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> --- src/current/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/AGENTS.md b/src/current/AGENTS.md index 473a8ac96dc..1c286e0df67 100644 --- a/src/current/AGENTS.md +++ b/src/current/AGENTS.md @@ -42,6 +42,6 @@ The includes are all located in subdirectories of the `_include` directory, i.e. - `_include/common` for widely shared things - `_include/cockroachcloud` for Cloud -- `_include/v25.4` for v25.4 docs +- `_include/v25.4` for v25.4-specific content