updating with diagrams and enterprise security sections

website/docs/feature-flag-tutorials/use-cases/gradual-rollout.md

@@ -3,31 +3,29 @@ title: How to Perform a Gradual Rollout
 slug: /feature-flag-tutorials/use-cases/gradual-rollout
 ---
 
-## What is a gradual rollout?
+## What is a Gradual Rollout?
 
-A gradual rollout is a controlled release strategy where a new feature is first released to a small subset of users. This allows for monitoring user behavior, identifying potential issues, and gathering feedback before a full-scale launch. It also allows us to experiment quickly and safely.
+A **gradual rollout** is a controlled release strategy where a new feature is first released to a small subset of users. This allows for monitoring user behavior, identifying potential issues, and gathering feedback before a full-scale launch. It also allows us to experiment quickly and safely.
 
-Unleash is a feature flag management platform that simplifies this process. This controlled approach allows development and operations teams to identify and mitigate risks. By exposing the new feature to a limited audience, potential issues, bugs, or performance bottlenecks can be detected and addressed early on, preventing widespread impact.
+By exposing the new feature to a limited audience, potential issues, bugs, or performance bottlenecks can be detected and addressed early on, preventing widespread impact.
 
-Developers also use gradual rollouts to gather user feedback. Early adopters provide valuable insights into user experience, usability, and feature effectiveness, enabling rapid improvements. Gradual rollouts are also significant for testing in production. Real-world usage patterns and performance can be monitored closely, helping to ensure the new release is ready for a broader user base. Managing traffic allows developers to control and gradually increase the number of users exposed to the new feature. This helps to manage system load and prevent performance degradation.
+This diagram below scopes out the process and structure of a gradual rollout implementation using Unleash. In this use case tutorial, you'll learn the recommended method of configuring a gradual rollout with your application and Unleash.
+
+![A breakdown of the entire scope of implementing a gradual rollout.](/img/tutorial-gradual-rollout-diagram.png)
+
+Developers also use gradual rollouts to gather user feedback. Early adopters provide valuable insights into user experience, usability, and feature effectiveness, enabling rapid improvements. Gradual rollouts are also significant for testing in production. Real-world usage patterns and performance can be monitored closely, helping to ensure the new release is ready for a broader user base.
 
 The key benefits of gradual rollouts are that you can experiment rapidly on a controlled group and roll back quickly if the experiment goes wrong. This reduces the risk of failure, improves software quality, improves user experience, and optimizes resource utilization.
 
 ## How to Perform a Gradual Rollout with Unleash
 
 In order to set up a gradual rollout, you will need:
 
-1. A place to host a feature flag management service
-2. An API Token
-3. An application & an Unleash SDK
-
-We are going to walk through these steps to perform a gradual rollout.
+-   A place to host a feature flag management service
+-   An API Token
+-   An application & an Unleash SDK
 
-## Hosting a feature flag management service
-
-In order to set up your systems to create and manage a gradual rollout, you’ll need to decide where to host a feature flag management service. This is a critical component of creating features that will hide behind a feature flag for a gradual rollout.
-
-There are two primary options for deciding where to host a service:
+In order to set up your systems to create and manage a gradual rollout, you’ll need to decide where to host a feature flag management service. This is a critical component of creating features that will hide behind a feature flag for a gradual rollout. There are two primary options for deciding where to host a service:
 
 -   Self-hosted: Deploy Unleash on your infrastructure (e.g., Docker, Kubernetes).
 -   Hosted by Unleash
@@ -36,40 +34,19 @@ Follow our documentation on [Self-Hosting with Unleash](/using-unleash/deploy/ge
 
 With Unleash set up, you can use your application to talk to Unleash through one of our SDKs.
 
-## Setting up your application and Unleash SDK
-
-In order to connect your application to Unleash you will need an SDK (software developer kit) for your programming language. The SDK will handle connecting to the Unleash server instance and retrieving feature flags based on your configuration. All versions of Unleash (OSS, Pro, and Enterprise) use the same client SDKs. Unleash provides official client SDKs for a number of programming languages.
-
-For example, if you are using a JavaScript-based client-side application, you’ll need the JavaScript SDK to install and reference in your application. The code block below displays how the code would look to reference a JavaScript Unleash SDK and a configuration object that includes the URL instance of your Unleash service and the API token that was generated in a previous section.
-
-```javascript
-import { Unleash } from "unleash-proxy-client";
-
-const unleash = new Unleash({
-    url: "http://localhost:4242/api/frontend",
-    appName: "my-app",
-    instanceId: "my-instance",
-    clientKey: YOUR_API_KEY,
-});
-```
-
-With your feature flag management service, your application, an API token, and an Unleash SDK added to your application, you are now able to set up and manage a gradual rollout with a feature flag.
-
-## Configuring Gradual Rollouts in Unleash
-
 To perform a gradual rollout, we will need to create the feature flag that will implement the rollout strategy. In the next section, we will explore what strategies are and how they are configured in Unleash.
 
 In the projects view, the Unleash platform shows a list of feature flags that you’ve generated. Click on the ‘New Feature Flag' button to create a new feature flag.
 
-![Create a new feature flag in Unleash for your gradual rollout strategy.](/img/react-tutorial-create-new-flag.png)
+![Create a new feature flag in Unleash.](/img/react-tutorial-create-new-flag.png)
 
 Next, you will create a feature flag on the platform and turn it on for your app.
 
 The feature flag we are creating is considered a ‘Release’ flag type. The project will be ‘Default’ or the named project in which you are working in for the purpose of this tutorial. As the number of feature flags grows, you can organize them in your projects. Read our docs on [Projects](/reference/projects) to learn more about how to configure and manage them for your team/organization. A description of the flag can help properly identify its specific purposes. However, this field is optional.
 
-The API Command bar is to the right of the flag form, which gives developers the option to use a curl command to create the flag with all the fields listed in the UI form straight from your terminal on your machine. If you wish to use the API command as an alternative, fill out the form before copying the command as it is automatically updated with the field inputs.
+The API Command bar is to the right of the flag form, which gives developers the option to use a curl command to create the flag with all the fields listed in the UI form straight from your terminal on your machine. If you wish to use the API command as an alternative, fill out the form before copying the command, as it is automatically updated with the field inputs.
 
-![Fill out the feature flag form.](/img/react-tutorial-create-flag-form.png)
+![Create a feature flag by filling out the form fields.](/img/react-tutorial-create-flag-form.png)
 
 Once you have completed the form, you can click ‘Create feature flag’.
 
@@ -81,7 +58,9 @@ Next, we will configure the gradual rollout strategy for your new flag.
 
 ## Implementing Gradual Rollout Activation Strategy
 
-Activation strategies let you enable a feature only for a specified audience.
+An important Unleash concept that enables developers to perform a gradual rollout is an [activation strategy](/reference/activation-strategies). An activation strategy defines who will be exposed to a particular flag or flags. Unleash comes pre-configured with multiple activation strategies that let you enable a feature only for a specified audience, depending on the parameters under which you would like to release a feature.
+
+![Anatomy of an activation strategy](/img/anatomy-of-unleash-strategy.png)
 
 Different strategies use different parameters. Predefined strategies are bundled with Unleash. The default strategy is the gradual rollout strategy with 100% rollout, which basically means that the feature is enabled for all users. In this case, we have only enabled the flag in the development environment for all users in the previous section.
 
@@ -98,7 +77,7 @@ You can configure your gradual rollout strategy using the following parameters i
     -   You can also enable **custom stickiness** by creating a context field for it to use in your gradual rollout. Learn more about [custom stickiness](/reference/stickiness#enabling-custom-stickiness).
     -   **groupId** is used to ensure that different flags will be evaluated differently. The `groupId` defaults to feature flag name, but the user can override it to _correlate rollout_ of multiple feature flags.
 
-![](/img/tutorial-grad-rollout-form.png)
+![Image of a gradual rollout form in Unleash](/img/tutorial-grad-rollout-form.png)
 
 There are two more advanced extensions of the gradual rollout strategy that you will see available to customize in the gradual rollout form:
 
@@ -107,46 +86,58 @@ There are two more advanced extensions of the gradual rollout strategy that you
 
 Constraints and variants are not required for a gradual rollout. These additional customizations can be built on top of the overall rollout strategy should you need more granular conditions for your feature beyond the rollout percentage.
 
+[Strategy variants](/reference/strategy-variants) can expose a particular version of a feature to select user bases when a flag is enabled. From there, a way to use the variants is to view the performance metrics and see which is more efficient. We can create several variations of this feature to release to users and gather performance metrics to determine which one yields better results.
+
+![List of activation strategies](/img/tutorial-activation-strategies-list.png)
+
+In the diagram above, we list and describe all the activation strategies Unleash offers. The default strategy and gradual rollout strategy are the only two that support _both_ variants and constraints. The remaining stategies can only add constraints.
+
 For gradual rollouts, _strategy constraints_ are most applicable for more granular conditions of a feature release.
 
 In the next section, we’ll explore how to apply a strategy constraint on top of a gradual rollout for more advanced use cases.
 
 ## Applying Strategy Constraints
 
-When utilizing an activation strategy such as a gradual rollout, it may be necessary to further define which subset of users get access to a feature and when the rollout takes place, depending on the complexity of your use case. Unleash provides [Strategy Constraints](/reference/strategy-constraints) as a way to fine-tune conditions under which a feature flag is evaluated. Within a gradual rollout activation strategy, you can use strategy constraints to, for example:
+When utilizing an activation strategy such as a gradual rollout, it may be necessary to further define which subset of users get access to a feature and when the rollout takes place, depending on the complexity of your use case. Unleash provides [strategy constraints](/reference/strategy-constraints) as a way to fine-tune conditions under which a feature flag is evaluated.
+
+![This diagram breaks down how strategy constraints sit on top activation strategies for flags in Unleash.](/img/tutorial-building-blocks-strategy-constraints.png)
+
+Within a gradual rollout activation strategy, you can use strategy constraints to, for example:
 
 -   roll out a feature only to users in a specific region
 -   schedule a feature to be released at a specific time
 -   make a feature available for a limited time only
 -   release a feature to users with one of a set of email addresses
 -   and any other targeting based on information you know about the user
 
-![](/img/tutorial-constraints-form.png)
+![You can configure your strategy constraints in the gradual rollout form.](/img/tutorial-constraints-form.png)
 
 Add constraints to refine the rollout based on user attributes, segments, or conditions.
 
 To learn more, read our docs on:
 
-1.  [Strategy Constraints](/reference/strategy-constraints)
+1.  [Strategy constraints](/reference/strategy-constraints)
 2.  [How to add strategy constraints](/how-to/how-to-add-strategy-constraints)
 
 ### Define Custom Context Fields for Strategy Constraints
 
 If you want to create new types of constraints that are not built into Unleash, you can create custom context fields and apply them to your constraints. Follow our [how-to guide on creating custom context fields](/how-to/how-to-define-custom-context-fields) to use in your gradual rollout for more advanced use cases.
 
-## Leverage Segments
+## Leveraging Segments
 
-A segment is a reusable collection of strategy constraints. Like with strategy constraints, you apply segments to feature flag activation strategies.
+A [segment](/reference/segments) is a reusable collection of [strategy constraints](/reference/strategy-constraints). Like with strategy constraints, you apply segments to feature flag activation strategies.
 
 You can apply the same segment to multiple activation strategies. If you update the segment, the changes will affect every strategy that uses that segment.
 
+![The anatomy of an Unleash segment in relation to a flag and associated strategy.](/img/anatomy-of-unleash-segments.png)
+
 Segments let you create user groups based on data available in the Unleash context. These groups can be as simple or as complex as you want to make them. For example, you could use segments to target:
 
 -   Users in a specific region
 -   Users on a specific device type
 -   Users who signed up before a specific point in time
 
-![](/img/segments-page.png)
+![In the top navigation menu in Unleash, go to Configure and then 'Segments' to manage your segments.](/img/segments-page.png)
 
 Because segments stay in sync across strategies, any changes will propagate to all the activation strategies that use them. This also makes them ideal for use cases such as activating or deactivating multiple feature flags at the same time. You can use segments to:
 
@@ -155,6 +146,64 @@ Because segments stay in sync across strategies, any changes will propagate to a
 -   create events with start and end times and guarantee that features will only be active during that period
     -   target the feature flag to specific segments
 
-You must pass the relevant fields in your context in the SDK in order for gradual rollout to work in a predictable way and for any of your constraints or segments to function the way you expect.
+You must pass the relevant fields in your context in the SDK in order for gradual rollout to work in a predictable way and for any of your constraints or segments to function the way you expect. Learn more about [configuring Unleash contexts](/reference/unleash-context) correctly for your app in our documentation.
+
+By following these steps and leveraging Unleash's features, you can effectively execute and refine gradual rollouts to minimize risks and optimize feature delivery.
+
+## Managing Gradual Rollouts With Enterprise Security In Mind
+
+For large-scale organizations, managing feature flags across many teams can be complex and challenging. Unleash was architected for your feature flag management to be scalable and traceable for enterprises, which boosts overall internal security posture while delivering software efficiently.
+
+After you have implemented a gradual rollout strategy, we recommend managing them by:
+
+-   Tracking performance of feature releases within your application
+-   Reviewing audit logs of each change to your flag configurations over time by project collaborators within your organization, which is exportable for reporting
+-   Reviewing and approving change requests to your flags and strategy configurations
+
+Read our documentation on how to effectively manage [feature flags at scale](/topics/feature-flags/best-practices-using-feature-flags-at-scale) while reducing security risks. Let’s walk through these recommended Unleash features in the subsequent sections.
+
+### Application Metrics
+
+[Unleash metrics](/reference/api/unleash/metrics) are a great way to understand user traffic. With your application using feature flags, you can review:
+
+-   How many requests for a specific feature per application environment are being made over periods of time
+-   How much exposure to users a feature has
+-   What time of day do requests increase
+
+![We have a Metrics graph in Unleash to review flag exposure and request rates.](/img/react-ex-metrics.png)
+
+When managing a gradual rollout, leverage metrics to gain deeper insight into flag usage against your application over time. For large-scale organizations with many feature flags to manage, this can be a useful monitoring tool for individual flags you would like to keep track of.
+
+### Reviewing Audit Logs
+
+Because a feature flag service controls the way an application behaves in production, it can be highly important to have visibility into when changes have been made and by whom. This is especially true in highly regulated environments. In these cases, you might find audit logging useful for:
+
+-   Organizational compliance
+-   Change control
+
+Fortunately, this is straightforward in Unleash Enterprise.
+
+Unleash provides the data to log any change that has happened over time, at the flag level from a global level. In conjunction with Unleash, tools like Splunk can help you combine logs and run advanced queries against them. Logs are useful for downstream data warehouses or data lakes.
+
+![The event log for a feature flag. The "Event log" tab is highlighted and the UI shows the most recent changes, including a JSON diff and the change details.](/img/unleash-toggle-history.png)
+
+Learn more about [event logs](/reference/event-log/) in our documentation.
+
+### Managing Change Requests
+
+You can use Unleash's [change request](/reference/change-requests) feature to propose and review modifications to feature flags. This gives developers complete control over your production environment. In large scale organizations and heavily regulated industries, we want to help developers reduce risk of errors in production or making unwanted changes by team members that have not been properly reviewed and approved.
+
+The [change request](/reference/change-requests) configuration can be set up per project, per environment. This means that you can have different change request configurations for different environments, such as production and development. This is useful because different environments may have different requirements, so you can customize the change request configuration to fit those requirements.
+
+Currently, there are two configuration options for change requests:
+
+-   **Enable change requests** - This boolean value enables or disables change requests for the project and environment.
+-   **Required approvals** - This is an integer value that indicates how many approvals are required before a change request can be applied. Specific permissions are required to approve and apply change requests.
+
+The change request configuration can be set up in the project settings page:
+
+![Change request configuration page under project settings.](/img/react-ex-project-settings.png)
+
+Learn more about all of the functionality available with [Change Requests](/reference/change-requests) in our documentation.
 
 By following these steps and leveraging Unleash's features, you can effectively execute and refine gradual rollouts to minimize risks and optimize feature delivery.