docs: add breaking changes page for cross-namespace default change

website/docs/breaking-changes.md

@@ -0,0 +1,48 @@
+---
+title: "Breaking Changes"
+sidebar_position: 99
+---
+
+# Breaking Changes
+
+This page tracks upcoming breaking changes to ACK controller defaults and behavior. Review this page before upgrading your controllers.
+
+## Cross-Namespace References Default Change
+
+:::warning[Breaking Change Notice]
+The default value of `--enable-cross-namespace` will change from `true` to `false` in a future release. The warning condition serves as a deprecation notice of existing default functionality.
+:::
+
+### Summary
+
+Cross-namespace resource references (including `*Ref` fields, `SecretKeyReference`, and `FieldExport` targets across namespaces) will require explicit opt-in to improve namespace isolation.
+
+### Timeline
+
+| Phase | Description |
+|:------|:------------|
+| **Phase 1 (current)** | Flag added with default `true`. Warning condition set on resources using cross-namespace references |
+| **Phase 2**<br/>**(future release)** | Flag default changes to `false`. Cross-namespace references rejected unless opted in |
+
+### Who is affected
+
+You are affected if any of your ACK resources:
+- Use `*Ref` fields pointing to resources in a **different namespace**
+- Use `SecretKeyReference` with a `namespace` field different from the resource's namespace
+- Use `FieldExport` CRs targeting ConfigMaps/Secrets in a different namespace than the source
+
+If all your references are within the same namespace, **no action is needed**.
+
+### Action required
+
+If you use cross-namespace references, explicitly opt in before upgrading to the Phase 2 release:
+
+```yaml
+# values.yaml
+enableCrossNamespace: true
+```
+
+Or via controller flag:
+```
+--enable-cross-namespace=true
+```

website/docs/contributing/index.md

@@ -40,6 +40,18 @@ The [ack-dev-skills](https://github.com/aws-controllers-k8s/ack-dev-skills) proj
 
 If you use AI coding tools (Claude Code, Kiro, Cursor, etc.), installing this skill will significantly improve the quality of AI-assisted ACK development work. See the [ack-dev-skills README](https://github.com/aws-controllers-k8s/ack-dev-skills) for installation instructions.
 
+## Documenting Breaking Changes
+
+If your PR introduces a breaking change (e.g., changing a default value, removing a flag, altering reconciliation behavior), you must update the [Breaking Changes](/docs/breaking-changes) page.
+
+Add an entry with:
+- A clear description of what is changing
+- Timeline (if phased rollout)
+- Who is affected
+- Action required for users to migrate
+
+This ensures users are informed before upgrading their controllers.
+
 ## Community
 
 - [GitHub Issues](https://github.com/aws-controllers-k8s/community/issues) — Bug reports and feature requests

website/sidebars.ts

@@ -29,7 +29,6 @@ const sidebars: SidebarsConfig = {
           type: 'doc',
           id: 'getting-started-eks',
           label: 'Using EKS Capabilities',
-          className: 'sidebar-item-new',
         },
         {
           type: 'doc',
@@ -81,7 +80,6 @@ const sidebars: SidebarsConfig = {
           type: 'doc',
           id: 'guides/cross-account',
           label: 'Granular IAM Roles',
-          className: 'sidebar-item-new',
         },
         {
           type: 'doc',
@@ -97,7 +95,6 @@ const sidebars: SidebarsConfig = {
           type: 'doc',
           id: 'guides/kro',
           label: 'Using ACK with kro',
-          className: 'sidebar-item-new',
         },
       ],
     },
@@ -114,6 +111,7 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: 'Contributing',
+      className: 'sidebar-category-new',
       collapsed: true,
       items: [
         'contributing/index',
@@ -135,6 +133,12 @@ const sidebars: SidebarsConfig = {
         'contributing/releasing',
       ],
     },
+    {
+      type: 'doc',
+      id: 'breaking-changes',
+      label: 'Breaking Changes',
+      className: 'sidebar-item-new',
+    },
   ],
 };
 

website/src/css/custom.css

@@ -191,3 +191,19 @@ pre {
   overflow-x: auto;
 }
 
+
+/* New badge for category headers only (not children) */
+.sidebar-category-new > .menu__list-item-collapsible > .menu__link > span::after {
+  content: 'New';
+  padding: 2px 6px;
+  margin-left: 8px;
+  font-size: 0.65rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  background: linear-gradient(135deg, #ff9520 0%, #ff6b00 100%);
+  color: white;
+  border-radius: 4px;
+  white-space: nowrap;
+  position: absolute;
+  right: 30px;
+}