Skip to content

docs(feature-flags): add the Feature Flags documentation page - #5962

Merged
dreamorosi merged 9 commits into
mainfrom
docs/feature-flags-page
Nov 17, 2026
Merged

dreamorosi merged 9 commits into
mainfrom
docs/feature-flags-page

Conversation

@dreamorosi

Copy link
Copy Markdown
Contributor

Summary

Replace the Feature Flags documentation stub with the full utility page, so developers can go from installation to an evaluated flag and understand how the utility relates to Powertools for Python and to AppConfig multi-variant flags. Also complete the package README and API reference setup. Part of RFC discussion #5614 and #3754.

Changes

  • Write docs/features/feature-flags.md, structured like the Signer and Parameters pages:
    • when to use Feature Flags versus Parameters;
    • installation for each sub-path, IAM permissions, the AppConfig Agent layer, and its minimum version;
    • the Flag Document format, with tables of all Actions and membership rules;
    • evaluation semantics, including Python-style truthiness for enabled;
    • time-based flags and MODULO_RANGE;
    • Standard Schema validation;
    • every Store, including envelopes and custom Stores, and multi-variant flags with their context rules;
    • the failure contract and error classes, and logging;
    • the differences from Powertools for Python 3.36.0, matching the conformance suite;
    • testing guidance with an in-memory Store, an injected clock, and Agent local mode.
  • Include every code block from examples/snippets/feature-flags/: 25 includes, with new snippets, Flag Document JSON fixtures, and test examples. They follow the snippet conventions in CODING_STANDARDS.md.
  • Replace the package README stub with an intro, install, usage example, and a link to the docs page.
  • Add packages/feature-flags/typedoc.json, with one entry point per public sub-path, as the other packages do.
  • Export EnvelopeOptions, EvaluateSchemaResult, EvaluateVariantOptions, EvaluateManyVariantOptions, and EvaluateManyVariantResult from the types entry point. They appear in public signatures but had no export, so callers couldn't import them and TypeDoc couldn't document them.
  • Tag AppConfigStoreOptions and AppConfigAgentStoreOptions with @expand, so their fields render inline on the store function pages.

mkdocs build --strict still fails on two existing generated-navigation warnings (api/ and ./llms.txt), not on this page. The non-strict build passes, and markdownlint, snippet lint, and snippet type-checks pass.

Issue number: closes #5908


By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

Document local rules, Agent variants, result validation, failure handling, and testing.

Refs #5908
EnvelopeOptions, EvaluateSchemaResult, and the Variant evaluation option and
result types appear in public signatures but had no export, so the API
reference could not include them and callers could not import them.
Tag both options types with @expand so TypeDoc renders their fields inline
on the store function pages. Their intersection with EnvelopeOptions keeps
TypeDoc from attaching the options.* @PARAM lines.
@powertools-for-aws-oss-automation powertools-for-aws-oss-automation Bot added the size/XXL PRs with 1K+ LOC, largely documentation related label Nov 12, 2026
…nt flags

The Lambda extension and the standalone Agent container use different
version numbers. Version 2.0.230173 is the standalone container build used
to verify the RFC, so stating it as the minimum excluded every published
Lambda extension layer, whose latest release is 2.0.27899. State the
Lambda extension release that added multi-variant flags instead.

Refs #5909
Comment thread docs/features/feature-flags.md Resolved
@dreamorosi
dreamorosi enabled auto-merge (squash) November 17, 2026 22:56
@dreamorosi
dreamorosi merged commit 69c4178 into main Nov 17, 2026
43 checks passed
@dreamorosi
dreamorosi deleted the docs/feature-flags-page branch November 17, 2026 23:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/XXL PRs with 1K+ LOC, largely documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: Feature Flags documentation page and snippets

2 participants