DOCS-3029: Improve openings of OSS resource reference pages by ctauchen · Pull Request #3010 · tigera/docs

ctauchen · 2026-09-04T10:04:33Z

Cleans up the openings of the Calico Open Source resource reference pages, in next and in versions 3.30, 3.31, and 3.32.

https://tigera.atlassian.net/browse/DOCS-3029

Move the calicoctl alias sentence in networkset.mdx out of the NAT note it was accidentally merged into
Fix a heading level skip in caliconodestatus.mdx and rewrite its ungrammatical opening
Sentence case for BGP Filter, expand BGP and IPAM at first paragraph-level mention, backticks on resource kinds, small grammar fixes
The same fixes applied to each versioned tree

Page titles are unchanged per review. A tip explaining Calico vs Kubernetes network policy is split out as https://tigera.atlassian.net/browse/DOCS-3030.

Representative changed pages on the deploy preview:

netlify · 2026-09-04T10:04:39Z

✅ Deploy Preview succeeded!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`514b8e8`
🔍 Latest deploy log	https://app.netlify.com/projects/tigera/deploys/6a9ab70d84779e0008ad356c
😎 Deploy Preview	https://deploy-preview-3010--tigera.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 66 (🔴 down 19 from production) Accessibility: 98 (no change from production) Best Practices: 92 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-09-04T10:04:47Z

✅ Deploy Preview for calico-docs-preview-next ready!

Name	Link
🔨 Latest commit	`514b8e8`
🔍 Latest deploy log	https://app.netlify.com/projects/calico-docs-preview-next/deploys/6a9ab70db01c2700086b8abd
😎 Deploy Preview	https://deploy-preview-3010--calico-docs-preview-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

🟡 Changes recommended

There is a minor but concrete documentation clarity issue in the updated bgpfilter.mdx opening sentence that should be reworded to avoid ambiguity.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR refines the introductory text and headings across Calico Open Source resource reference pages to remove duplication, improve readability, and standardize terminology/formatting.

Changes:

Updated several page H1 titles to avoid duplication with section/category titles.
Improved opening paragraphs for multiple resources (grammar, acronym expansion, and consistent backticks for resource kinds).
Adjusted structure/placement of notes and introductory content for clarity (for example, NetworkSet alias note and CalicoNodeStatus notes heading level).

File summaries

File	Description
calico/reference/resources/tier.mdx	Fixes punctuation so the “example use cases” lead-in correctly introduces the list.
calico/reference/resources/stagedkubernetesnetworkpolicy.mdx	Corrects capitalization in the opening sentence for consistency/readability.
calico/reference/resources/overview.mdx	Retitles the page to avoid duplicated “Resource definitions” heading.
calico/reference/resources/networkset.mdx	Formats the resource kind with backticks, improves grammar, and moves `calicoctl` alias info out of the NAT note.
calico/reference/resources/networkpolicy.mdx	Retitles the page to avoid duplicated “Network policy” heading.
calico/reference/resources/ipamconfig.mdx	Expands IPAM on first use and clarifies the opening sentence.
calico/reference/resources/globalnetworkset.mdx	Formats the resource kind with backticks for consistency.
calico/reference/resources/caliconodestatus.mdx	Rewrites the opening for clearer usage explanation and fixes heading hierarchy for Notes.
calico/reference/resources/blockaffinity.mdx	Clarifies what the affinity represents and explains that these are automatically managed.
calico/reference/resources/bgppeer.mdx	Expands BGP on first use and improves clarity of the opening explanation.
calico/reference/resources/bgpfilter.mdx	Sentence-case heading and expands BGP; clarifies the opening description.
calico/reference/resources/bgpconfig.mdx	Expands BGP on first use and improves clarity of the opening explanation.

Review details

Files reviewed: 12/12 changed files
Comments generated: 1
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

🟢 Approval recommended

Changes are documentation-only and appear safe/consistent across “next” and versioned trees, with only a minor clarity nit noted.

Review details

Files reviewed: 48/48 changed files
Comments generated: 4
Review effort level: Lite

ctauchen · 2026-09-04T12:01:14Z


-A block affinity resource (`BlockAffinity`) represents the affinity for an IPAM block. These are managed by Calico IPAM.
+A block affinity resource (`BlockAffinity`) represents the affinity between a node and an IP address management (IPAM) block.
+$[prodname] IPAM creates and manages these resources automatically; you don't normally need to create or modify them.


Confirm and provide evidence.

Confirmed. calicoctl has no resource manager for BlockAffinity, so it cannot create, apply, or delete them; the type appears only in IPAM internals (libcalico-go/lib/ipam/ipam_block_reader_writer.go claims and releases affinities). The Calico Enterprise page for the same resource lists Create/Delete/Update as No in its Supported operations table. Kept the hedge (normally) because the v3 API server registers create and update strategies.

ctauchen · 2026-09-04T12:03:09Z

-# BGP Filter
+# BGP filter

 A BGP filter resource (`BGPFilter`) represents a way to control


Spell out at first paragraph-level mention. See IPAMConfiguration for model.

Done in 514b8e8, and applied the same pattern to bgpconfig.mdx and bgppeer.mdx for consistency.

ctauchen · 2026-09-04T12:06:50Z

 ---

-# Network policy
+# Calico network policy


This is a calico network policy, but it diverges from the model for resource reference pages. Return to the title based on the resource name. Add a new ticket to add tip explaining difference between calico and kubernets network policy

Reverted to Network policy in 514b8e8. Ticket for the tip: https://tigera.atlassian.net/browse/DOCS-3030

ctauchen · 2026-09-04T12:07:16Z

 in that namespace. Two resources are in the same namespace if the `namespace`
 value is set the same on both. (See [GlobalNetworkSet](globalnetworkset.mdx) for non-namespaced network sets.)

+For `calicoctl` commands that specify a resource type on the CLI, the following


Confirm and provide evidence.

Confirmed. calicoctl/calicoctl/resourcemgr/networkset.go registers the aliases networkset, networksets, netsets, and lookup is case-insensitive via strings.ToLower in resourcemgr.go line 372.

ctauchen · 2026-09-04T12:07:48Z

 ---

-# Resource definitions
+# About resource definitions


Return to original

Reverted in 514b8e8.

Copilot

🟡 Changes recommended

A small grammar issue (“Status … is collected”) was introduced in the updated CalicoNodeStatus opening sentence across multiple doc versions and should be corrected for readability.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files reviewed: 48/48 changed files
Comments generated: 4
Review effort level: Lite


-As of today, status of BGP agents, BGP sessions and routes exposed to BGP agents are collected from Linux nodes only. **Windows nodes are not supported at this time.**
-Calico node status resource is only valid when $[prodname] BGP networking is in use.
+Status of Border Gateway Protocol (BGP) agents, BGP sessions, and routes exposed to BGP agents is collected from Linux nodes only. **Windows nodes are not supported at this time.**



-As of today, status of BGP agents, BGP sessions and routes exposed to BGP agents are collected from Linux nodes only. **Windows nodes are not supported at this time.**
-Calico node status resource is only valid when $[prodname] BGP networking is in use.
+Status of Border Gateway Protocol (BGP) agents, BGP sessions, and routes exposed to BGP agents is collected from Linux nodes only. **Windows nodes are not supported at this time.**



-As of today, status of BGP agents, BGP sessions and routes exposed to BGP agents are collected from Linux nodes only. **Windows nodes are not supported at this time.**
-Calico node status resource is only valid when $[prodname] BGP networking is in use.
+Status of Border Gateway Protocol (BGP) agents, BGP sessions, and routes exposed to BGP agents is collected from Linux nodes only. **Windows nodes are not supported at this time.**



-As of today, status of BGP agents, BGP sessions and routes exposed to BGP agents are collected from Linux nodes only. **Windows nodes are not supported at this time.**
-Calico node status resource is only valid when $[prodname] BGP networking is in use.
+Status of Border Gateway Protocol (BGP) agents, BGP sessions, and routes exposed to BGP agents is collected from Linux nodes only. **Windows nodes are not supported at this time.**


Copilot

🟢 Approval recommended

The changes are straightforward documentation wording/formatting improvements with consistent application across the targeted versioned trees and no issues found in the updated MDX structure.

Review details

Files reviewed: 40/40 changed files
Comments generated: 0 new
Review effort level: Lite

DOCS-3029: Improve openings of OSS resource reference pages

68e3bee

Copilot AI lite review requested due to automatic review settings September 4, 2026 10:04

ctauchen requested a review from a team as a code owner September 4, 2026 10:04

Copilot started reviewing on behalf of ctauchen September 4, 2026 10:05 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

Comment thread calico/reference/resources/bgpfilter.mdx Outdated

DOCS-3029: Apply the same opening fixes to OSS 3.30-3.32

21e82fc

Copilot AI review requested due to automatic review settings September 4, 2026 11:42

Copilot started reviewing on behalf of ctauchen September 4, 2026 11:43 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

DOCS-3029: Address review comments

fa42a6e

Copilot AI review requested due to automatic review settings September 4, 2026 12:11

Copilot started reviewing on behalf of ctauchen September 4, 2026 12:12 View session

ctauchen commented Sep 4, 2026

View reviewed changes

Copilot AI reviewed Sep 4, 2026

View reviewed changes

DOCS-3029: Restore H1s and expand BGP at first mention

514b8e8

Copilot AI review requested due to automatic review settings September 4, 2026 12:18

Copilot started reviewing on behalf of ctauchen September 4, 2026 12:18 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

ctauchen mentioned this pull request Sep 4, 2026

DOCS-3032: Improve openings of CE resource reference pages #3011

Merged

ctauchen merged commit 28b3ddf into tigera:main Sep 4, 2026
11 checks passed

ctauchen mentioned this pull request Sep 4, 2026

DOCS-3033: Improve openings of CC resource reference pages #3012

Merged

Uh oh!

Conversation

ctauchen commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview succeeded!

Uh oh!

netlify Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for calico-docs-preview-next ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ctauchen commented Sep 4, 2026 •

edited

Loading

netlify Bot commented Sep 4, 2026 •

edited

Loading

netlify Bot commented Sep 4, 2026 •

edited

Loading