Skip to content

[FFL-3457] Document flag selection for the browser SDK - #41060

Open
mark-caii wants to merge 17 commits into
masterfrom
mark.cai/FFL-3457
Open

mark-caii wants to merge 17 commits into
masterfrom
mark.cai/FFL-3457

Conversation

@mark-caii

@mark-caii mark-caii commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do? What is the motivation?

Ticket: FFL-3457

Documents the flagSelection option of the browser SDK (@datadog/openfeature-browser), which loads only the flags that match a set of tags or key patterns.

  • feature_flags/client/javascript.md: adds flagSelection to the provider options table and a Load a subset of flags section covering matching rules (exact, case-sensitive tags; whole-key globs where only * is special; tags OR key patterns), limits (31 values per list, 200 UTF-8 bytes per value), what happens when a selection is dropped by the SDK or ignored by Datadog (DD-Flag-Selection-Ignored reasons), FLAG_NOT_FOUND for flags outside the selection, initialFlagsConfiguration not being filtered, and fetchRulesConfiguration() support.
  • feature_flags/guide/proxy_sdk_traffic.md: the Browser tab notes that a proxy must pass through DD-Flag-Selection-Ignored and expose it with Access-Control-Expose-Headers.

Merge readiness

  • Ready for merge

The section names @datadog/openfeature-browser 2.2.0, the first release that includes flagSelection, as the minimum version.

AI assistance

Drafted with Claude Code from the SDK README and source; reviewed against the SDK behavior.

For Datadog employees:

  • ⚠️ Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). If you've already created your PR with an incorrect branch name, please rename your branch and open a fresh PR.
  • 🤖 New: Comment with /review to run an automated check that catches common issues before a Documentation team member reviews your PR.

Additional notes

Other client SDK pages and the API reference are not part of this PR.

Add a Load a subset of flags section to the JavaScript client page and a proxy note for the DD-Flag-Selection-Ignored header.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added the Guide Content impacting a guide label Oct 27, 2026
@github-actions

Copy link
Copy Markdown
Contributor

mark-caii and others added 8 commits October 27, 2026 16:16
Nest the Load a subset of flags section under Initialize the provider, since flagSelection is set when the provider is created.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Add the OpenFeature.getClient() call to the Evaluate flags outside the selection example, since client is otherwise first defined in the later Get a client section.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Set the minimum @datadog/openfeature-browser version to 2.2.0 and note that Datadog returns the full configuration without DD-Flag-Selection-Ignored when flag selection is not enabled for the organization.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Flag selection is rolling out globally, so the no-header case no longer refers to per-organization enablement.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Remove the no-header case and state that flags outside the selection are not loaded.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Lead with the risk that team tags change with ownership, and render it as a WARNING callout.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
List each limit on its own line so the 31-value limit is not read as a combined total.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Matches MAX_RULES_URL_BYTES and the too_many_values console error in @datadog/openfeature-browser 2.2.0.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@mark-caii
mark-caii marked this pull request as ready for review October 28, 2026 15:16
@mark-caii
mark-caii requested a review from a team as a code owner October 28, 2026 15:16
mark-caii and others added 3 commits October 28, 2026 15:32
State that too_many_values also covers selections too long for one request, document that empty selections load the full configuration silently, and scope the Access-Control-Expose-Headers requirement to cross-origin proxies.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Add the two console error templates the browser SDK logs when it does not send a flag selection or when Datadog ignores it.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
State in one sentence that flagSelection does not filter configuration supplied with initialFlagsConfiguration.

Environment: Datadog workspace

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@maycmlee maycmlee self-assigned this Oct 28, 2026
@maycmlee

Copy link
Copy Markdown
Contributor

Created DOCS-16170 for review

@maycmlee maycmlee added the editorial review Waiting on a more in-depth review label Oct 28, 2026
@maycmlee maycmlee removed their assignment Oct 28, 2026

@joepeeples joepeeples left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this new content, @mark-caii! I flagged a few possible edits, and one overall structural suggestion: Consider moving Load a subset of flags under Configure browser provider options, as an H3. Where it sits now, it interrupts the basic setup flow with an optional, advanced feature.

Feel free to ping directly when ready for a quick re-review, thanks!

@mark-caii
mark-caii requested a review from a team as a code owner November 9, 2026 15:08

Copy link
Copy Markdown
Contributor Author

On the structural suggestion in the review: moved Load a subset of flags under Configure browser provider options as an H3, after Set a timeout and retries for flag configuration requests, in d8e1dfc. The #load-a-subset-of-flags anchor is unchanged, so the options table link and the link from the proxy guide still resolve.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

editorial review Waiting on a more in-depth review Guide Content impacting a guide

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants