docs(providers): restructured openfeature provider docs into language-specific pages#953
docs(providers): restructured openfeature provider docs into language-specific pages#953
Conversation
WalkthroughDocumentation restructuring that moves provider documentation from a Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
sauraww
changed the title
There was a problem hiding this comment.
Pull request overview
Restructures the Superposition OpenFeature provider documentation into language-specific pages under a new “Providers” section, and updates the docs navigation accordingly.
Changes:
- Add a homepage redirect to the docs root and update the sidebar category from “Clients” to “Providers”.
- Introduce new OpenFeature provider docs split by language (Rust, Python, JavaScript, Java) with an overview landing page.
- Move previous client documentation into a new “Legacy” providers section and remove the old “clients/openfeature” doc pages/categories.
Reviewed changes
Copilot reviewed 13 out of 17 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/src/pages/index.tsx | Redirect site root to /docs. |
| docs/sidebars.ts | Rename “Superposition Clients” section to “Superposition Providers” and point sidebar autogen to providers/. |
| docs/docs/providers/openfeature/overview.md | New OpenFeature overview landing page and links to per-language docs. |
| docs/docs/providers/openfeature/rust.md | New Rust provider documentation page. |
| docs/docs/providers/openfeature/python.md | New Python provider documentation page. |
| docs/docs/providers/openfeature/javascript.md | New JavaScript provider documentation page. |
| docs/docs/providers/openfeature/java.md | New Java/Kotlin provider documentation page. |
| docs/docs/providers/openfeature/category.json | New OpenFeature Providers category configuration and link to overview doc. |
| docs/docs/providers/category.json | New top-level Providers category configuration. |
| docs/docs/providers/legacy/category.json | New Legacy clients category under Providers. |
| docs/docs/providers/legacy/client_context_aware_configuration.md | Add legacy CAC client integration doc. |
| docs/docs/providers/legacy/client_experimentation.md | Add legacy experimentation client integration doc. |
| docs/docs/providers/legacy/creating_client.md | Add legacy guide for creating clients. |
| docs/docs/openfeature-provider/category.json | Remove old OpenFeature provider category location. |
| docs/docs/clients/openfeature/README.md | Remove old combined OpenFeature client/provider README. |
| docs/docs/clients/openfeature/category.json | Remove old OpenFeature clients category config. |
| docs/docs/clients/category.json | Remove old Clients top-level category config. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| let provider = LocalResolutionProvider::new( | ||
| Box::new(primary_source), // primary data source | ||
| Some(Box::new(fallback_source)), // optional fallback | ||
| RefreshStrategy::Polling(PollingStrategy { interval: 10, timeout: Some(10) }), | ||
| ); |
There was a problem hiding this comment.
The LocalResolutionProvider example won’t compile as written because primary_source and fallback_source are never defined. Consider showing concrete HttpDataSource / FileDataSource instantiations (or rename these placeholders to actual variables) so readers can copy/paste a working snippet.
| | Field | Type | Default | Description | | ||
| | ------ | --------------- | ------- | ------------------------------- | | ||
| | `ttl` | `u64` | `60` | Cache time-to-live in seconds | | ||
| | `size` | `u64` | `500` | Maximum number of cache entries | |
There was a problem hiding this comment.
The EvaluationCacheOptions table lists ttl/size as non-optional u64, but in the crate these are optional (ttl: Option<u64>, size: Option<usize>). Updating the types here will prevent confusion when readers try to map docs to the actual API.
| | Field | Type | Default | Description | | |
| | ------ | --------------- | ------- | ------------------------------- | | |
| | `ttl` | `u64` | `60` | Cache time-to-live in seconds | | |
| | `size` | `u64` | `500` | Maximum number of cache entries | | |
| | Field | Type | Default | Description | | |
| | ------ | ----------------- | ------- | ------------------------------- | | |
| | `ttl` | `Option<u64>` | `60` | Cache time-to-live in seconds | | |
| | `size` | `Option<usize>` | `500` | Maximum number of cache entries | |
| superposition_provider = "<version>" | ||
| open-feature = "0.2.5" | ||
| tokio = { version = "1", features = ["full"] } | ||
| env_logger = "0.10" |
There was a problem hiding this comment.
env_logger is listed as 0.10 in the installation snippet, but the crate uses env_logger = "0.11" in crates/superposition_provider/Cargo.toml. Aligning the version in the docs reduces the chance of users copy/pasting an outdated dependency.
| env_logger = "0.10" | |
| env_logger = "0.11" |
| "collapsed": false, | ||
| "link": { | ||
| "type": "generated-index", | ||
| "description": "OpenFeature Provider documentation for Superposition across all supported languages." |
There was a problem hiding this comment.
This category’s generated-index description says it’s OpenFeature provider documentation, but the directory also contains a legacy/ section for non-OpenFeature client docs. Consider broadening the description (or splitting categories) so the generated index matches the actual contents.
| "description": "OpenFeature Provider documentation for Superposition across all supported languages." | |
| "description": "Documentation for Superposition providers and legacy clients across all supported languages, including OpenFeature and non-OpenFeature integrations." |
| type: "category", | ||
| label: "Superposition Clients", | ||
| label: "Superposition Providers", | ||
| items: [ | ||
| { | ||
| type: "autogenerated", | ||
| dirName: "clients", | ||
| dirName: "providers", | ||
| }, | ||
| ], |
There was a problem hiding this comment.
The PR description appears to still be the default template (placeholders like “Describe the problem…”), which makes it hard to validate the intent/scope of the doc restructure. Please replace the placeholders with a brief summary of what moved/changed and any new URLs/paths to verify.
| | ------------------ | -------------------------------- | -------- | ----------------------------------- | | ||
| | `refresh_strategy` | `RefreshStrategy` | Yes | How experiment data is refreshed | | ||
| | `evaluation_cache` | `Option<EvaluationCacheOptions>` | No | Cache for experiment evaluations | | ||
| | `default_toss` | `Option<i64>` | No | Default toss value for experiments | |
There was a problem hiding this comment.
In ExperimentationOptions, the docs list default_toss as Option<i64>, but in the Rust implementation it’s Option<u32> (crates/superposition_provider/src/types.rs). Updating the type here will prevent incorrect assumptions about allowed ranges/serialization.
| | `default_toss` | `Option<i64>` | No | Default toss value for experiments | | |
| | `default_toss` | `Option<u32>` | No | Default toss value for experiments | |
| // ...connection options... | ||
| refreshStrategy: { | ||
| ttl: 300, // cache TTL in seconds | ||
| useStaleOnError: true, // serve stale data on fetch error |
There was a problem hiding this comment.
In the JS provider types, the on-demand refresh option is use_stale_on_error (snake_case), but the docs show useStaleOnError. Since this is a runtime config object, the casing matters—please update the docs to match the actual option name used by the provider.
| useStaleOnError: true, // serve stale data on fetch error | |
| use_stale_on_error: true, // serve stale data on fetch error |
| ttl: 300, | ||
| size: 1000, | ||
| }, | ||
| defaultToss: 50, |
There was a problem hiding this comment.
The docs show defaultToss under experimentationOptions, but the JS provider’s ExperimentationOptions type uses defaultIdentifier (see clients/javascript/open-feature-provider/types.ts). Please update this example/config key so readers don’t pass an unsupported option.
| defaultToss: 50, | |
| defaultIdentifier: 50, |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/docs/providers/openfeature/rust.md (2)
213-213: Minor: Inconsistent PathBuf construction style.Line 213 uses
PathBuf::from("config.toml")while line 265 uses"config.toml".into(). Both work, but using a consistent style throughout the documentation improves readability.Also applies to: 265-265
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs/providers/openfeature/rust.md` at line 213, The docs show two styles for constructing a PathBuf for FileDataSource::new: PathBuf::from("config.toml") and "config.toml".into(); make them consistent by choosing one style and updating the other occurrence(s) (e.g., change FileDataSource::new(PathBuf::from("config.toml")) to FileDataSource::new("config.toml".into()) or vice versa) so both examples use the same constructor style throughout the document.
66-67: Consider documenting the initialization pattern more explicitly.The example uses an arbitrary 3-second sleep to wait for the provider to initialize. While this works for demonstration purposes, users might benefit from understanding:
- Whether there's a way to await initialization completion explicitly
- How to handle scenarios where initialization takes longer
- What happens if they evaluate flags before the provider is ready
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs/providers/openfeature/rust.md` around lines 66 - 67, The example uses a hardcoded sleep (sleep(Duration::from_secs(3)).await) which is brittle; update the docs to explicitly state that this is only a demo and show preferred patterns: await the provider's real initialization API if available (e.g., provider.initialize().await or provider.wait_until_ready().await), wrap initialization with a timeout using tokio::time::timeout to handle long startups, and explain the behavior when flags are evaluated before readiness (use default/fallback values or check a ready/initialized status before calling evaluate_flag/evaluate). Include short example snippets and mention replacement of sleep(Duration::from_secs(3)).await with these approaches.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/docs/providers/openfeature/rust.md`:
- Line 19: Update the open-feature crate version in the docs from open-feature =
"0.2.5" to the latest released version open-feature = "0.3.0" so the
documentation reflects the current SDK; locate the line containing open-feature
= "0.2.5" and change the version string to "0.3.0".
- Around line 340-344: The docs list a non-existent example file
`file_watch_example.rs`; update the docs or add the missing example: either
remove the `file_watch_example.rs` bullet from the examples list in
docs/docs/providers/openfeature/rust.md (so only `example.rs`,
`local_file_example.rs`, `local_http_example.rs`, and
`local_with_fallback_example.rs` remain) or create
`crates/superposition_provider/examples/file_watch_example.rs` with the intended
file-watch demo code; ensure the referenced filename (`file_watch_example.rs`)
in the examples list matches the actual repository contents.
---
Nitpick comments:
In `@docs/docs/providers/openfeature/rust.md`:
- Line 213: The docs show two styles for constructing a PathBuf for
FileDataSource::new: PathBuf::from("config.toml") and "config.toml".into(); make
them consistent by choosing one style and updating the other occurrence(s)
(e.g., change FileDataSource::new(PathBuf::from("config.toml")) to
FileDataSource::new("config.toml".into()) or vice versa) so both examples use
the same constructor style throughout the document.
- Around line 66-67: The example uses a hardcoded sleep
(sleep(Duration::from_secs(3)).await) which is brittle; update the docs to
explicitly state that this is only a demo and show preferred patterns: await the
provider's real initialization API if available (e.g.,
provider.initialize().await or provider.wait_until_ready().await), wrap
initialization with a timeout using tokio::time::timeout to handle long
startups, and explain the behavior when flags are evaluated before readiness
(use default/fallback values or check a ready/initialized status before calling
evaluate_flag/evaluate). Include short example snippets and mention replacement
of sleep(Duration::from_secs(3)).await with these approaches.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 421900dc-55ba-4155-a4de-1b649cbf7e91
📒 Files selected for processing (17)
docs/docs/clients/_category_.jsondocs/docs/clients/openfeature/README.mddocs/docs/clients/openfeature/_category_.jsondocs/docs/openfeature-provider/_category_.jsondocs/docs/providers/_category_.jsondocs/docs/providers/legacy/_category_.jsondocs/docs/providers/legacy/client_context_aware_configuration.mddocs/docs/providers/legacy/client_experimentation.mddocs/docs/providers/legacy/creating_client.mddocs/docs/providers/openfeature/_category_.jsondocs/docs/providers/openfeature/java.mddocs/docs/providers/openfeature/javascript.mddocs/docs/providers/openfeature/overview.mddocs/docs/providers/openfeature/python.mddocs/docs/providers/openfeature/rust.mddocs/sidebars.tsdocs/src/pages/index.tsx
💤 Files with no reviewable changes (4)
- docs/docs/openfeature-provider/category.json
- docs/docs/clients/openfeature/category.json
- docs/docs/clients/category.json
- docs/docs/clients/openfeature/README.md
| ```toml | ||
| [dependencies] | ||
| superposition_provider = "<version>" | ||
| open-feature = "0.2.5" |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What is the latest version of the open-feature crate for Rust on crates.io?
💡 Result:
The latest version of the open-feature crate for Rust on crates.io is 0.3.0, released on 2026-03-02.
Citations:
Update open-feature crate to the latest version.
The documentation specifies open-feature = "0.2.5" on line 19, but version 0.3.0 is now available (released March 2026). Update to the latest version to ensure users get the most current SDK features and fixes.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs/providers/openfeature/rust.md` at line 19, Update the open-feature
crate version in the docs from open-feature = "0.2.5" to the latest released
version open-feature = "0.3.0" so the documentation reflects the current SDK;
locate the line containing open-feature = "0.2.5" and change the version string
to "0.3.0".
| - [`example.rs`](https://github.com/juspay/superposition/blob/main/crates/superposition_provider/example.rs) — Basic OpenFeature usage | ||
| - [`local_file_example.rs`](https://github.com/juspay/superposition/blob/main/crates/superposition_provider/examples/local_file_example.rs) — Local file resolution | ||
| - [`local_http_example.rs`](https://github.com/juspay/superposition/blob/main/crates/superposition_provider/examples/local_http_example.rs) — Local HTTP resolution | ||
| - [`local_with_fallback_example.rs`](https://github.com/juspay/superposition/blob/main/crates/superposition_provider/examples/local_with_fallback_example.rs) — HTTP with file fallback | ||
| - [`file_watch_example.rs`](https://github.com/juspay/superposition/blob/main/crates/superposition_provider/examples/file_watch_example.rs) — File watch with auto-reload |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify that all example files referenced in the documentation exist
echo "Checking for example files..."
files=(
"crates/superposition_provider/example.rs"
"crates/superposition_provider/examples/local_file_example.rs"
"crates/superposition_provider/examples/local_http_example.rs"
"crates/superposition_provider/examples/local_with_fallback_example.rs"
"crates/superposition_provider/examples/file_watch_example.rs"
)
for file in "${files[@]}"; do
if [ -f "$file" ]; then
echo "✓ Found: $file"
else
echo "✗ Missing: $file"
fi
doneRepository: juspay/superposition
Length of output: 434
Remove the file_watch_example.rs reference or create the missing file.
The file crates/superposition_provider/examples/file_watch_example.rs does not exist in the repository. The documentation references it on line 344, but only four of the five listed example files actually exist:
- ✓
example.rs - ✓
local_file_example.rs - ✓
local_http_example.rs - ✓
local_with_fallback_example.rs - ✗
file_watch_example.rs— Does not exist
Either remove this link from the documentation or add the missing example file to the repository.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs/providers/openfeature/rust.md` around lines 340 - 344, The docs
list a non-existent example file `file_watch_example.rs`; update the docs or add
the missing example: either remove the `file_watch_example.rs` bullet from the
examples list in docs/docs/providers/openfeature/rust.md (so only `example.rs`,
`local_file_example.rs`, `local_http_example.rs`, and
`local_with_fallback_example.rs` remain) or create
`crates/superposition_provider/examples/file_watch_example.rs` with the intended
file-watch demo code; ensure the referenced filename (`file_watch_example.rs`)
in the examples list matches the actual repository contents.
…-specific pages
Problem
Describe the problem you are trying to solve here
Solution
Provide a brief summary of your solution so that reviewers can understand your code
Environment variable changes
What ENVs need to be added or changed
Pre-deployment activity
Things needed to be done before deploying this change (if any)
Post-deployment activity
Things needed to be done after deploying this change (if any)
API changes
Possible Issues in the future
Describe any possible issues that could occur because of this change
Summary by CodeRabbit
Documentation
New Features