[RUM-13811] Add feature doc sync system for *_FEATURE.md files#2886
[RUM-13811] Add feature doc sync system for *_FEATURE.md files#2886mariedm wants to merge 10 commits into
Conversation
mariedm
force-pushed
the
mariedm/RUM-13811/feature-docs-sync
branch
from
3b8fec5 to
4bbe62d
Compare
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4bbe62d430
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0610945b93
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
mariedm
force-pushed
the
mariedm/RUM-13811/feature-docs-sync
branch
2 times, most recently
from
6bc779c to
b584ef3
Compare
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b584ef3afc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cab13ec55e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cab13ec55e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Per review feedback, the workflow registration check now verifies the two distinct contexts (the trigger paths: filter and the cp block) separately. Previously a single substring match would silently pass if only one of the two was present, which left a footgun where a doc-only update would not trigger publishing, or the page would never get copied.
`git diff <commit>..HEAD -- <missing-path>` exits 0 with empty stdout, so a typo or stale renamed path in a doc's frontmatter would silently report as "up to date". Validate each tracked path resolves to a file in the working tree before invoking git diff, and surface the missing entries with the standard fix recipe.
Multiple coverage gaps in the RUM and Session Replay feature docs
flagged across two review passes:
- RUM: tracked_files was missing DatadogRUM/Sources/RUMMonitor.swift.
The doc's "Public API" section documents `RUMMonitor.shared(in:)`
(the entry point for manual instrumentation), but the file was not
tracked, so changes there could drift the doc while CI stayed green.
- Session Replay: tracked_files was missing three public-API source
files explicitly referenced in the doc's "Key Files" section:
- SessionReplayPrivacyOverrides.swift (UIKit per-view privacy)
- SessionReplayPrivacyView.swift (SwiftUI per-view privacy)
- DatadogInternal/.../SessionReplayConfiguration.swift (privacy
level enums)
- Session Replay: doc enumerated SessionReplay.Configuration.FeatureFlag
cases but omitted the still-public deprecated `screenChangeScheduling`.
Document it in both the Quick Start example comment and the
"Available feature flags" reference list, with a clear deprecation
note.
Strengthen the update-feature-docs skill to prevent both classes of
issue from recurring:
- Step 2 now audits 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. The audit happens before the diff
in step 3, otherwise drift in untracked files is silently ignored.
- Step 5 now explicitly calls out deprecated public cases. Deprecated
`@available(*, deprecated, message:)` enum cases, methods, and
properties remain on the public API and must be documented with a
deprecation note.
The audit step in step 2 caught the additional RUM and SR gaps when
the skill was re-run — confirming the prevention works.
Bump verified_against_commit and last_updated on both docs.
Swift named-argument calls must follow the initializer declaration order. In RUMConfiguration.init, trackSlowFrames sits between trackMemoryWarnings and telemetrySampleRate, but the Quick Start snippet placed it after telemetrySampleRate and collectAccessibility, so copy-pasting the example produced an "argument 'trackSlowFrames' must precede argument 'telemetrySampleRate'" compile error. Move trackSlowFrames into the correct slot and bump frontmatter.
GitLab CI shallow-clones at depth 20 by default. tools/feature-docs-verify.sh runs `git diff <verified_against_commit>..HEAD` per doc, which requires the baseline commit to be in the local history. On release/hotfix branches, any doc whose verified_against_commit is older than 20 commits would otherwise silently fail the diff before the script can actually verify anything — turning a CI configuration quirk into a doc-verification false alarm. Stable feature docs that go several releases without changes would hit this every time on any bounded depth. The job is scoped to release/* and hotfix/* branches (a handful of runs per release cycle), so a full clone is the simplest reliable answer.
mariedm
force-pushed
the
mariedm/RUM-13811/feature-docs-sync
branch
from
64219c2 to
743ff7e
Compare
1 participant
What and why
RUM_FEATURE.mdandSESSION_REPLAY_FEATURE.mdhad drifted from the current public API (last verified against SDK 3.3.0). This PR refreshes them to 3.10.0 and puts a CI guard in place so they can't silently drift again — covering not just the docs themselves, but every place that hand-lists them (AGENTS.md, the LLM guidelines, and the Confluence publish workflow).What changes
Three moving parts:
The docs.
RUM_FEATURE.mdandSESSION_REPLAY_FEATURE.mdbrought up to SDK 3.10.0. Each doc gains YAML frontmatter (tracked_files,verified_against_commit) so it is its own source of truth for what to watch.A verify script —
tools/feature-docs-verify.sh, run viamake feature-docs-verify, wired into a newFeature Docs VerifyGitLab CI job onrelease/*andhotfix/*branches. It checks two things for every discovered*_FEATURE.md:AGENTS.md,docs/LLM_FEATURE_DOCS_GUIDELINES.md, and.github/workflows/changelog-to-confluence.yaml.A Claude Code skill —
/dd-sdk-ios:update-feature-docs— that owns the refresh workflow, including keeping those three registries in sync when a doc is added/renamed/removed. Engineers don't need to memorize the touchpoints; the script + skill close the loop.Read more in this internal doc.
Notable
changelog-to-confluence.yamlhad leading slashes in its `paths:` filter (`'/DatadogRUM/RUM_FEATURE.md'`), which never match in GitHub Actions filters. The pages still got published, but only as a side effect of `CHANGELOG.md` triggering the workflow on releases (the `cp` block always runs once triggered). Doc-only updates have never triggered publishing on their own. Removed.Review checklist