Repository navigation
Conversation
👷 Deploy request for calico-docs-preview-next pending review.Visit the deploys page to approve it
|
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Four unresolved documentation and template issues leave the agent guidance incomplete and the reference-page templates grammatically unfinished.
4 open issues
What changed in this PR
Adds a standardized resource-reference template and converts the IPReservation, IPPool, and BGPPeer pages to demonstrate the new structure. It also adds contributor guidance, supporting content templates, agent instructions, and updates an IPPool selector link.
Changes:
- Adds contributor documentation and templates for documentation content types.
- Introduces the resource-reference template with consistent sections and field tables.
- Converts three Calico resource-reference pages to the new format.
- Updates selector-anchor references and agent guidance.
| File | Summary |
|---|---|
contributors/style-guide.md |
Adds contributor style-guide guidance. |
contributors/README.md |
Adds navigation for contributor documentation and templates. |
contributors/content-types/templates/tutorial.mdx |
Adds the tutorial template. |
contributors/content-types/templates/troubleshooting.mdx |
Adds the troubleshooting template. |
contributors/content-types/templates/resource.mdx |
Adds the standardized resource-reference template. |
contributors/content-types/templates/reference.mdx |
Adds the general reference template and resource-template guidance. |
contributors/content-types/templates/installation-guide.mdx |
Adds the installation-guide template. |
contributors/content-types/templates/how-to.mdx |
Adds the how-to template. |
contributors/content-types/templates/explanation.mdx |
Adds the explanation template. |
contributors/content-types/content-types.md |
Documents available content types and their intended uses. |
CLAUDE.md |
Points agents to repository instructions. |
calico/reference/resources/ipreservation.mdx |
Converts the IPReservation page to the resource-reference structure. |
calico/reference/resources/ippool.mdx |
Converts the IPPool page and updates behavior and selector sections. |
calico/reference/resources/bgppeer.mdx |
Converts the BGPPeer page with nested type sections and standardized tables. |
calico/reference/configure-calico-node.mdx |
Updates the IPPool selector anchor link. |
AGENTS.md |
Adds guidance for selecting content types and templates. |
This pull request is too complex or risky for automated approval.
Review effort: Lite
ctauchen
force-pushed
the
docs-3100-resource-template
branch
from
November 5, 2026 16:40
003ecfd to
fa4b205
Compare
The resource pages use 16 table layouts, 25 wordings for the definition heading, three ways to mark a required field, and six layouts for the supported operations table. The template fixes one structure: a lead paragraph that gives the scope and the owner, a sample manifest, a Definition section with Metadata, Spec, nested types, and Status, behavior sections after it, and additional resources. Every table has the same five columns. There is no supported operations table; the lead paragraph says what the reader can't do. Converts three Calico Open Source pages as worked examples: IP reservation, IP pool, and BGP peer. The conversions change structure and the metadata name rule, not the facts on the page.
kubectl lowercases the resource name in an alias but not the group, so the aliases aren't case-insensitive. Drop the word on the three converted pages and in the template, and say why in the template. Finish the two sentences that stopped at "describes."
ctauchen
force-pushed
the
docs-3100-resource-template
branch
from
November 12, 2026 15:41
fa4b205 to
263c918
Compare
The list of types was a copy of content-types.md and would drift from it as types are added. Keep the list in one place.
FelixConfiguration renders its Spec from generated JSON, so it can't use the field table. StagedKubernetesNetworkPolicy inherits its fields from a Kubernetes type. Shared includes own their headings and anchors across products. The overview and index pages aren't resource pages. Say so in the template, so the remaining conversions don't fight it.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Approval is blocked by two active issues: the IPPool page lacks the required status schema, and the resource template renders an unimported Selectors component that can break builds.
2 open issues
4 resolved since last review
Review effort: Lite
|
|
||
| ### Selector | ||
|
|
||
| <Selectors /> |
| ``` | ||
|
|
||
| ## IP pool definition | ||
| ## Definition |
Copilot pointed out that the IP pool page mentions the Allocatable condition but has no Status section, which the template requires. Add one. The conditions come from kube-controllers in native v3 CRD mode only, so say so. Allocatable with OK, PoolDisabled, and CIDROverlap were checked on a kind cluster running 3.33 in that mode. The template rendered Selectors without importing it, so a copied page would not build. Add the import with guidance.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a template for resource reference pages, so that every page in reference/resources/ has the same sections, in the same order, with the same table columns. The 98 existing pages use 16 table layouts, 25 wordings for the definition heading, three ways to mark a required field, and six layouts for the supported operations table.
Jira: https://tigera.atlassian.net/browse/DOCS-3100
Changes:
New claims on the converted pages, and what they were checked against:
scopeat every published version.Preview: