[RUM-13811] Add feature doc sync system for *_FEATURE.md files

.claude/skills/update-feature-docs/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: dd-sdk-ios:update-feature-docs
+description: Use when public API changes have been made to review and update all *_FEATURE.md documentation files, or to audit whether they are still accurate.
+---
+
+# update-feature-docs
+
+Review and update the feature documentation files to match the current public API.
+
+## When to use
+
+- After adding or modifying a public API (configuration options, new types, new methods)
+- Before opening a release PR, to make sure docs are in sync
+- Any time you want to audit whether feature docs are still accurate
+
+## What this skill covers
+
+All `*_FEATURE.md` files in the repo. Each doc's frontmatter is the source of truth:
+- `verified_against_commit` — the commit the doc was last verified against
+- `tracked_files` — the public API source files whose changes should trigger a doc update
+
+To add a new feature doc to the system, just create a `*_FEATURE.md` file with the correct frontmatter — no script changes needed.
+
+## Steps
+
+1. **Discover feature docs** — find all `*_FEATURE.md` files in the repo (excluding `build/` and `artifacts/`).
+
+2. **For each doc, read its frontmatter** — extract `verified_against_commit` and `tracked_files`.
+   - If `tracked_files` is missing, derive the list from the doc's "Key Files" section (every source file path it references). Treat the doc as fully out of date and proceed to step 4 — the diff in step 3 cannot be computed.
+   - If `verified_against_commit` is missing, treat the doc as fully out of date and proceed to step 4 — the diff in step 3 cannot be computed.
+   - **Audit `tracked_files` coverage** against the doc's "Key Files" section. Every public-API source file path referenced in "Key Files" must also appear in `tracked_files`. This audit must happen *here*, before step 3 — otherwise drift in untracked files is silently ignored. If any are missing, add them to `tracked_files` and treat the doc as fully out of date so the newly-tracked files are inspected in step 4.
+
+3. **Get the diff since that commit** — run:
+   ```
+   git diff <verified_against_commit>..HEAD -- <tracked_files>
+   ```
+   If there is no diff for a doc, it is up to date — skip steps 4–7 for that doc and move to the next one. **Do not skip step 8** — registry coverage must be checked even when every doc is fresh.
+
+4. **Read the current source files in full** — read each tracked source file to understand the current public API surface.
+
+5. **Compare against the feature doc** — identify every discrepancy:
+   - New configuration options or parameters missing from the doc
+   - Removed or renamed options still mentioned in the doc
+   - Changed defaults, behaviors, or platform availability
+   - New types, enums, or feature flags not documented
+   - **Deprecated public cases not documented** — walk every public enum case, method, and property, including those marked `@available(*, deprecated, message:)`. Deprecated cases stay on the public API and must appear in the doc with a clear deprecation note, otherwise customers reading the doc won't know they exist or that they're being phased out.
+   - Outdated code examples
+
+6. **Update the feature doc** — apply all necessary changes:
+   - Update the Quick Start example to reflect the current API
+   - Update the Configuration Categories section
+   - Update Troubleshooting if relevant
+   - Fix any stale descriptions or defaults
+
+7. **Update the frontmatter** — set:
+   - `tracked_files` → if it was missing or out of date, write the list derived in step 2
+   - `verified_against_commit` → current HEAD commit hash (use `git rev-parse --short=9 HEAD`)
+   - `sdk_version` → current version from `DatadogCore.podspec`
+   - `last_updated` → today's date (YYYY-MM-DD)
+
+8. **Update the registries** — when adding, renaming, or removing a `*_FEATURE.md` file, also update every place that hand-lists feature docs. `tools/feature-docs-verify.sh` enforces these and will fail CI otherwise:
+   - **`.github/workflows/changelog-to-confluence.yaml`** — both the `paths:` filter and the `cp` block. Use the relative path **without a leading slash** (`DatadogRUM/RUM_FEATURE.md`, not `/DatadogRUM/RUM_FEATURE.md`) — leading slashes silently never match in GitHub Actions `paths:` filters. The publish filename is kebab-case derived from the module + doc (`DatadogRUM/RUM_FEATURE.md` → `dd-sdk-ios-rum-feature.md`).
+   - **`AGENTS.md`** — add the doc to the file tree under "Feature-specific docs" and to the routing table ("Where to Look First").
+   - **`docs/LLM_FEATURE_DOCS_GUIDELINES.md`** — add the doc to the expected feature-docs list.
+
+## Notes
+
+- Only update docs for features whose tracked source files actually changed.
+- Do not rewrite sections that are still accurate — only fix what is wrong or missing.
+- The Quick Start example should always compile against the current API.

.github/workflows/changelog-to-confluence.yaml

@@ -5,8 +5,8 @@ on:
             - master
         paths:
             - 'CHANGELOG.md'
-            - '/DatadogRUM/RUM_FEATURE.md'
-            - '/DatadogSessionReplay/SESSION_REPLAY_FEATURE.md'
+            - 'DatadogRUM/RUM_FEATURE.md'
+            - 'DatadogSessionReplay/SESSION_REPLAY_FEATURE.md'
 permissions:
     contents: read
 jobs:

.gitlab-ci.yml

@@ -137,6 +137,21 @@ API Surface Verify:
     - make clean repo-setup ENV=ci
     - make api-surface-verify
 
+Feature Docs Verify:
+  stage: lint
+  rules:
+    - if: '$CI_COMMIT_BRANCH =~ /^(release|hotfix)\/.*/'
+  # tools/feature-docs-verify.sh runs `git diff <verified_against_commit>..HEAD`,
+  # which requires that commit to be reachable in the local history. GitLab CI
+  # shallow-clones at depth 20 by default, which would silently bury baselines
+  # for any feature doc that hasn't been touched in a few releases (e.g. Logs).
+  # The job only runs on release/hotfix branches (a handful of times per cycle),
+  # so the cost of a full clone is negligible.
+  variables:
+    GIT_DEPTH: "0"
+  script:
+    - make feature-docs-verify
+
 Unit Tests (iOS):
   stage: test
   rules: 

CLAUDE.md

@@ -19,6 +19,7 @@ Use these skills (via `/skill-name`) for common workflows:
 | `dd-sdk-ios:open-pr` | Opening a pull request against `develop` |
 | `dd-sdk-ios:running-tests` | Running unit, module, or integration tests |
 | `dd-sdk-ios:xcode-file-management` | Adding, removing, moving, or renaming Swift source files |
+| `dd-sdk-ios:update-feature-docs` | Review and update all `*_FEATURE.md` docs after public API changes |
 
 ## CI Environment
 

DatadogRUM/RUM_FEATURE.md

@@ -1,7 +1,12 @@
 ---
-last_updated: 2025-01-03
-sdk_version: 3.3.0
-verified_against_commit: 1d3e80ec5
+last_updated: 2026-05-11
+sdk_version: 3.10.0
+verified_against_commit: b584ef3af
+tracked_files:
+  - DatadogRUM/Sources/RUM.swift
+  - DatadogRUM/Sources/RUMConfiguration.swift
+  - DatadogRUM/Sources/RUMMonitor.swift
+  - DatadogRUM/Sources/RUMMonitorProtocol.swift
 ---
 
 # RUM (Real User Monitoring) Feature
@@ -48,12 +53,14 @@ RUM.enable(
         // Default: nil (disabled)
         // Or use custom: MyCustomViewsPredicate()
         // Note: Also requires uiKitViewsPredicate for SwiftUI tracking to work correctly
+        // Note: Experimental API - may change in future releases
         swiftUIViewsPredicate: DefaultSwiftUIRUMViewsPredicate(),
 
         // SwiftUI automatic action tracking - provide predicate to enable
         // Default: nil (disabled)
         // Or use custom: MyCustomActionsPredicate()
         // Note: Also requires uiKitActionsPredicate for SwiftUI tracking to work correctly
+        // Note: Experimental API - behavior differs between iOS 17 and below vs iOS 18+
         swiftUIActionsPredicate: DefaultSwiftUIRUMActionsPredicate(isLegacyDetectionEnabled: true),
 
         // Automatic network resource tracking - provide config to enable
@@ -67,7 +74,14 @@ RUM.enable(
             // Optional: Add custom attributes to resources
             resourceAttributesProvider: { request, response, data, error in
                 return ["custom.attribute": "value"]
-            }
+            },
+            // Optional: Capture HTTP headers from requests and responses
+            // Default: .disabled
+            // Options:
+            //   .disabled - No header capture
+            //   .defaults - Capture predefined common headers (cache-control, content-type, etag, etc.)
+            //   .custom([rules]) - Capture headers by custom rules
+            trackResourceHeaders: .defaults
         ),
 
         // Track user frustrations (error taps following errors)
@@ -142,13 +156,21 @@ RUM.enable(
         // Default: true
         trackMemoryWarnings: true,
 
+        // Track slow frames / view hitches
+        // Default: true
+        trackSlowFrames: true,
+
         // SDK telemetry sampling rate (for Datadog internal monitoring)
         // Default: 20.0
         telemetrySampleRate: 20.0,
 
         // Collect accessibility settings in view events
         // Default: false
-        collectAccessibility: false
+        collectAccessibility: false,
+
+        // Experimental feature flags (currently no active flags for RUM)
+        // Default: [:]
+        featureFlags: [:]
     )
 )
 
@@ -199,14 +221,16 @@ monitor.stopView(key: "ProductList")
 
 ### Automatic Tracking
 Requires configuration to be set, otherwise disabled by default:
-- **View tracking**: `uiKitViewsPredicate`, `swiftUIViewsPredicate`
-- **Action tracking**: `uiKitActionsPredicate`, `swiftUIActionsPredicate`
+- **View tracking**: `uiKitViewsPredicate`, `swiftUIViewsPredicate` *(SwiftUI: experimental)*
+- **Action tracking**: `uiKitActionsPredicate`, `swiftUIActionsPredicate` *(SwiftUI: experimental, behavior differs on iOS 17 vs iOS 18+)*
 - **Resource tracking**: `urlSessionTracking` (automatic), optionally call `URLSessionInstrumentation.enableDurationBreakdown(with: .init(delegateClass: YourSessionDelegate.self))` for detailed timing
+- **Header capture**: `urlSessionTracking.trackResourceHeaders` — `.disabled` (default), `.defaults` (common headers), or `.custom([rules])`
 
 ### Performance Monitoring
 - **Long tasks**: `longTaskThreshold` (default: 0.1s)
 - **App hangs**: `appHangThreshold` (default: nil/disabled)
 - **Vitals**: `vitalsUpdateFrequency` (default: .average)
+- **Slow frames**: `trackSlowFrames` (default: true) — captures view hitches and attaches them to the corresponding RUM view
 
 ### Sampling
 - **Sessions**: `sessionSampleRate` (default: 100%)
@@ -231,7 +255,7 @@ Event mappers allow modifying or dropping events before upload:
 ### "Views or actions not tracked"
 1. Check if predicates are configured in RUMConfiguration
 2. For UIKit: `uiKitViewsPredicate` and `uiKitActionsPredicate` must be set
-3. For SwiftUI: `swiftUIViewsPredicate` and `swiftUIActionssPredicate` must be set, as well as UIKit predicates
+3. For SwiftUI: `swiftUIViewsPredicate` and `swiftUIActionsPredicate` must be set, as well as UIKit predicates
 
 ### "Network requests not tracked"
 1. Verify `urlSessionTracking` is configured in RUMConfiguration (RUM.enable() handles URLSessionInstrumentation internally)

DatadogSessionReplay/SESSION_REPLAY_FEATURE.md

@@ -1,7 +1,13 @@
 ---
-last_updated: 2025-01-03
-sdk_version: 3.3.0
-verified_against_commit: 1d3e80ec5
+last_updated: 2026-05-12
+sdk_version: 3.10.0
+verified_against_commit: cab13ec55
+tracked_files:
+  - DatadogSessionReplay/Sources/SessionReplay.swift
+  - DatadogSessionReplay/Sources/SessionReplayConfiguration.swift
+  - DatadogSessionReplay/Sources/SessionReplayPrivacyOverrides.swift
+  - DatadogSessionReplay/Sources/SessionReplayPrivacyView.swift
+  - DatadogInternal/Sources/Models/SessionReplay/SessionReplayConfiguration.swift
 ---
 
 # Session Replay Feature
@@ -84,8 +90,13 @@ SessionReplay.enable(
 
         // Feature flags for experimental features
         // Default: [.swiftui: false]
+        // Available flags:
+        //   .swiftui                - Enable SwiftUI recording (experimental)
+        //   .heatmaps               - Enable heatmap identifier computation (experimental)
+        //   .screenChangeScheduling - DEPRECATED: now default and always enabled; setting it has no effect
         featureFlags: [
-            .swiftui: true  // Enable SwiftUI recording (experimental)
+            .swiftui: true,   // Enable SwiftUI recording (experimental)
+            .heatmaps: false  // Enable heatmap identifier computation (experimental)
         ]
     )
 )
@@ -218,6 +229,11 @@ SessionReplayPrivacyView(
 1. Enable SwiftUI feature flag: `featureFlags: [.swiftui: true]`
 2. Note: Session Replay SwiftUI is experimental, and some components are not supported
 
+### Available feature flags
+- `.swiftui` — Enable SwiftUI recording (experimental, default: `false`)
+- `.heatmaps` — Enable heatmap identifier computation (experimental, default: `false`)
+- `.screenChangeScheduling` — **Deprecated.** Screen change scheduling is now the default and always enabled; setting this flag has no effect. Kept on the public API for backward compatibility.
+
 ## Feature Interactions
 
 - **RUM**: Required - Session Replay cannot work without RUM enabled. View and action tracking must be configured.

Makefile

@@ -424,6 +424,11 @@ api-surface-verify:
 		--output-file /tmp/api-surface-objc-generated \
 		../../api-surface-objc
 
+# Verify feature doc files are up to date
+feature-docs-verify:
+	@$(ECHO_TITLE) "make feature-docs-verify"
+	@./tools/feature-docs-verify.sh
+
 # Builds API documentation using the same process as Swift Package Index.
 spi-docs-build:
 	@$(ECHO_TITLE) "make spi-docs-build"