From 99f621fcf229e7e2bcf9bdb1b6d6cfd779a3c62e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 21 Oct 2025 22:30:19 +0000
Subject: [PATCH] Update README with recent features since v3.1.1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added documentation for:
- Percentage-based rollouts and A/B testing feature
- rolloutStableId prop for Features component
- enableFor field in FeatureDescription type
- Node.js 18+ requirement
- Usage examples and best practices for gradual rollouts

This documents the major features added in PRs #35 and #34.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/README.md b/README.md
index ef0a58e..9b3d810 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,14 @@ Easy and fast way to toggle features in your project.
 Features include:
 
 - Toggle parts of your project dynamically or at startup
+- Percentage-based rollouts for gradual feature adoption and A/B testing
 - Built in state management for active features
 - Roll your own state manager using the minimal functional interface
 
 ## Installation and usage
 
+**Requirements:** Node.js 18.0.0 or higher
+
 To install,
 
 ```sh
@@ -51,6 +54,47 @@ function App(): JSX.Element {
 }
 ```
 
+## Percentage-based Rollouts and A/B Testing
+
+React-Enable supports gradual rollouts and A/B testing through percentage-based feature flags. This allows you to enable features for a specific percentage of users.
+
+```typescript
+import { Features, Enable } from 'react-enable';
+
+// Enable the feature for 30% of users
+const FEATURES: FeatureDescription[] = [
+  { name: 'newDesign', enableFor: 0.3 }  // 30% rollout
+];
+
+function App(): JSX.Element {
+  const userId = getUserId(); // Get a stable user identifier
+
+  return (
+    <Features features={FEATURES} rolloutStableId={userId}>
+      <Enable feature="newDesign">
+        <NewDesign />
+      </Enable>
+      <Disable feature="newDesign">
+        <OldDesign />
+      </Disable>
+    </Features>
+  );
+}
+```
+
+### Key Features
+
+- **Deterministic Assignment**: The same user (based on `rolloutStableId`) will always see the same features, ensuring consistent user experience
+- **Auto-generated IDs**: If `rolloutStableId` is not provided, an ID is automatically generated and persisted to sessionStorage
+- **Gradual Rollouts**: Easily increase feature adoption by adjusting the `enableFor` value (0.0 to 1.0)
+- **A/B Testing**: Use different percentage values to test multiple feature variants
+
+### Best Practices
+
+- Use a stable user identifier (user ID, session ID, etc.) for `rolloutStableId` to ensure consistency across page loads
+- Start with small percentages (e.g., 0.05 for 5%) and gradually increase as you validate the feature
+- Combine with manual overrides using `ToggleFeatures` component for testing
+
 ## Documentation
 
 ### `Features` component
@@ -60,11 +104,24 @@ Provides state and context for managing a set of features.
 Available props:
 
 - `features: FeatureDescription[]`: description of available features.
+- `rolloutStableId?: string`: stable identifier for percentage-based rollouts
+  (e.g., user ID, session ID). If not provided, an ID is auto-generated
+  and persisted to sessionStorage
 - `disableConsole?: boolean`: indicate the console API
   should not be enabled (default false)
 - `storage?: Storage`: where to persist
   overrides (default `window.sessionStorage`)
 
+### `FeatureDescription` type
+
+Defines a feature flag with the following properties:
+
+- `name: string`: unique identifier for the feature
+- `defaultValue?: boolean`: whether the feature is enabled by default (default false)
+- `enableFor?: number`: percentage of users to enable this feature for (0.0 to 1.0).
+  When specified, this takes precedence over `defaultValue` and uses deterministic
+  hashing based on `rolloutStableId` to ensure consistent assignment
+
 ### `Enabled` and `Disabled` components
 
 Render children depending on which set of features are active.