Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-02-28 00:17:12 +01:00
Code Issues Projects Releases Wiki Activity

Example Docs fixes (#6919)

Browse Source 
Hello, 

As discussed with @sighphyre, there were a number of problems with the
examples docs. This addresses the most pressing ones, namely:

- Corrected the link to the Jira plugin
- Added deprecation warning to Jira Server pages
- Removed the incomplete markdown table at the end of articles, and the
references to it

---------

Co-authored-by: Simon Hornby <liquidwicked64@gmail.com>
This commit is contained in:
Alvin Bryan 2024-04-26 17:22:16 +01:00 committed by GitHub
parent 0ac9624caf
commit d1cad6ece3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 160 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
website/docs/feature-flag-tutorials/java/spring-boot-examples.md
View File

@ -7,13 +7,16 @@ In our [Java Spring Boot feature flag tutorial](/feature-flag-tutorials/spring-b
We built multiple features into Unleash, an open-source feature flag platform, to address the complexities of releasing code and managing feature flags along the way. This tutorial will explore the following:
1. [Gradual rollouts](#gradual-rollouts-for-java-spring-boot-apps)
2. [Canary deployments](#canary-deployments-in-java)
3. [Server-side A/B testing](#server-side-ab-testing-in-java-spring-boot)
4. [Feature flag metrics & reporting](#feature-flag-analytics-and-reporting-in-java)
5. [Feature flag audit logs](#feature-flag-audit-logs-in-java)
6. [Flag automation & workflow integration](#flag-automation--workflow-integration-for-java-apps)
7. [Common usage examples of Spring Boot feature flags](#common-usage-examples-of-spring-boot-feature-flags)
- [Gradual Rollouts for Java Spring Boot Apps](#gradual-rollouts-for-java-spring-boot-apps)
- [Canary Deployments in Java](#canary-deployments-in-java)
- [What is a canary deployment?](#what-is-a-canary-deployment)
- [How to do canary deployments with a feature flag in Java?](#how-to-do-canary-deployments-with-a-feature-flag-in-java)
- [Configure strategy constraints for canary deployments](#configure-strategy-constraints-for-canary-deployments)
- [Server-side A/B Testing in Java Spring Boot](#server-side-ab-testing-in-java-spring-boot)
- [Feature Flag Analytics and Reporting in Java](#feature-flag-analytics-and-reporting-in-java)
- [Application Metrics \& Monitoring](#application-metrics--monitoring)
- [Feature Flag Audit Logs in Java](#feature-flag-audit-logs-in-java)
- [Flag Automation \& Workflow Integration for Java Apps](#flag-automation--workflow-integration-for-java-apps)
## Gradual Rollouts for Java Spring Boot Apps
@ -230,9 +233,11 @@ You can also retrieve event log data by using an API command. Read our documenta
## Flag Automation & Workflow Integration for Java Apps
An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. [Our Jira integration](/reference/integrations/jira-server-plugin-installation) helps to manage feature flag lifecycles associated with your projects.
An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. Our [Unleash Jira plugin](https://docs.getunleash.io/reference/integrations/jira-cloud-plugin-installation) helps to manage feature flag lifecycles associated with your projects.
It’s common for teams to have a development phase, QA/testing, and then a production release. Let’s say the changes we’ve made in our Java project must go through a typical development workflow. The [Unleash Jira plugin](https://marketplace.atlassian.com/apps/1227377/unleash-for-jira?tab=overview&hosting=datacenter) can connect to your Jira server or cloud to create feature flags automatically during the project creation phase. As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be Canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and/or roll out to target audiences in production.
It’s common for teams to have a development phase, QA/testing, and then a production release. Let’s say the changes we’ve made in our Java project must go through a typical development workflow.
As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be Canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and/or roll out to target audiences in production.
Here’s how this can be done via our API:
@ -290,37 +295,4 @@ Response response = client.newCall(request).execute();
Review [API docs on archiving flags](/reference/api/unleash/archive-feature).
## Common Usage Examples of Spring Boot Feature Flags
We’ve compiled a list of the most common functions to call in a Spring Boot app.
| Annotation | Description | Parameters |
| ---------- | ----------- | ---------- |
| [`@Toggle`](#toggle-example) | determines whether or not the flag is enabled | feature flag name (string), alterBean (string), variants |
| [`@FeatureVariant`](#featurevariant-and-featurevariants-example) | targets specific variant to reference | variant name (string), variantBean (string) |
| [`@FeatureVariants`](#featurevariant-and-featurevariants-example) | targets specific | Array of feature variants |
### `@Toggle` example
```java
@Toggle(name="demo-toggle", alterBean="featureNewService")
```
### `@FeatureVariant` and `@FeatureVariants` example
```java
@Toggle(name = "background-color-feature",
variants = @FeatureVariants(
fallbackBean = "noBackgroundColorService",
variants = {
@FeatureVariant(name = "green-background-variant", variantBean = "greenBackgroundColorService"),
@FeatureVariant(name = "red-background-variant", variantBean = "redBackgroundColorService")
}
)
)
```
Learn more about different use cases in our [Spring Boot Starter Kit](https://github.com/Unleash/unleash-spring-boot-starter) and [Java SDK](/reference/sdks/java).

99
website/docs/feature-flag-tutorials/python/examples.md
View File

@ -7,14 +7,17 @@ In our [Python feature flag tutorial](/feature-flag-tutorials/python), we implem
We built multiple features into Unleash, an open-source feature flag platform, to address the complexities of releasing code and managing feature flags along the way. This tutorial will explore the following:
1. [Gradual rollouts](#gradual-rollouts-for-python-apps)
2. [Canary deployments](#canary-deployments-in-python)
3. [Server-side A/B testing](#server-side-ab-testing-in-python)
4. [Feature flag metrics & reporting](#feature-flag-analytics-and-reporting-in-python)
5. [Feature flag audit logs](#feature-flag-audit-logs-in-python)
6. [Flag automation & workflow integration](#flag-automation--workflow-integration-for-python-apps)
7. [Common usage examples of Python feature flags](#common-usage-examples-of-python-feature-flags)
- [Gradual Rollouts for Python Apps](#gradual-rollouts-for-python-apps)
- [Canary Deployments in Python](#canary-deployments-in-python)
- [What is a canary deployment?](#what-is-a-canary-deployment)
- [How to do canary deployments with a Python feature flag?](#how-to-do-canary-deployments-with-a-python-feature-flag)
- [Configure strategy constraints for canary deployments](#configure-strategy-constraints-for-canary-deployments)
- [Server-side A/B Testing in Python](#server-side-ab-testing-in-python)
- [Feature Flag Analytics and Reporting in Python](#feature-flag-analytics-and-reporting-in-python)
- [Enable impression data events in Python](#enable-impression-data-events-in-python)
- [Application Metrics \& Monitoring for Python](#application-metrics--monitoring-for-python)
- [Feature Flag Audit Logs in Python](#feature-flag-audit-logs-in-python)
- [Flag Automation \& Workflow Integration for Python Apps](#flag-automation--workflow-integration-for-python-apps)
## Gradual Rollouts for Python Apps
@ -30,7 +33,6 @@ Adjust the percentage of users to 50% or whichever value you choose, and refresh
![A gradual rollout form can allow you to customize your flag strategy.](/img/ex-grad-rollout-form.png)
You can achieve this same result using our API with the following code:
```py
@ -65,18 +67,14 @@ print(response.text)
Learn more about [gradual rollouts in our docs](/reference/activation-strategies). Also, learn more about our [API for creating a new strategy](/reference/api/unleash/update-feature-strategy) for your flag.
## Canary Deployments in Python
### What is a canary deployment?
Canary releases are a way to test and release code in different environments for a subset of your audience, which determines which features or versions of the platform people have access to.
### How to do canary deployments with a Python feature flag?
Canary deployments are a safer and more gradual way to make changes in software development. They help find abnormalities and align with the agile process for faster releases and quick reversions.
Unleash has a few ways to help manage canary deployments for Python apps at scale:
@ -89,44 +87,36 @@ Unleash has a few ways to help manage canary deployments for Python apps at scal
Let’s walk through how to utilize **strategy constraints** in our Python app.
### Configure strategy constraints for canary deployments
We will build a strategy constraint on our existing gradual rollout strategy. This will allow us to target a subset of users for the rollout.
In Unleash, start from the feature flag view and edit your Gradual Rollout strategy from your development environment.
![Edit your gradual rollout strategy by selecting the 'edit strategy' button.](/img/ex-edit-strategy.png)
This will take you to the gradual rollout form. Next, add a new constraint.
![Add a constraint to your strategy.](/img/ex-add-constraint.png)
Let’s say we are experimenting with releasing the “delete” feature to all environments except production to test it with internal users before releasing it to all users.
![The new constraint form includes a context field, operator, and values field to customize the conditions under which a user will be exposed to the flag](/img/ex-constraint-page.png)
We can configure the constraint in the form to match these requirements:
- The context field is set to **environment**
- The operator is set to **NOT_IN**
- The value added is **production**
Once you’ve filled out the proper constraint fields, select ‘Done’ and save the strategy.
![Once you add a constraint, you can see it listed underneath your strategy in Unleash.](/img/python-ex-constraint-added.png)
Your release process is now configured with an environment-dependent strategy constraint. Since we've set the rollout to 100%, the feature will be released to all users that are not in the `production` environment.
Alternatively, you can send an API command to apply the same requirements:
```py
import requests
import json
@ -175,10 +165,8 @@ Check out our [API docs on updating flag strategies](/reference/api/unleash/upda
Read our documentation for more context on [strategy constraint configurations](/reference/strategy-constraints) and use cases.
## Server-side A/B Testing in Python
A/B testing is a common way for teams to test out how users interact with two or more versions of a new feature that is released. Server-side A/B testing can help with making infrastructure improvements and comparing different versions of server-side methods. At Unleash, we call these [strategy variants](/reference/strategy-variants).
When a feature flag is enabled, we can expose a particular version of a feature to select user bases. From there, we can use the variants to view the performance metrics in Unleash and see which is more efficient.
@ -195,7 +183,6 @@ In the form, add 2 variants:
`store_deleted_surveys` <br /> `permanently_delete_surveys`
![Two variants can be configured in Unleash and saved to your strategy.](/img/python-ex-strategy-variants-form.png)
Alternatively, you can also use a `PATCH` request in Python using our API:
@ -233,12 +220,10 @@ Your strategy now has 2 new variants.
![View the 2 feature variants we created in a 50/50 split between your users in the development environment.](/img/python-ex-variants-in-strategy.png)
Now that we have configured our strategy variant, we can reference it in our Python code.
In the `routes.py` file, we can modify the `delete_survey` method to split the user traffic between the 2 variants.
```py
def delete_survey(survey_id):
delete_survey_flag_variant = client.get_variant("delete_survey_flag")
@ -266,10 +251,8 @@ Now, some of the deleted surveys will be stored and the others will be permanent
Next, we can examine how Unleash can track the results and provide insights with data analytics.
## Feature Flag Analytics and Reporting in Python
Shipping code is one thing, but monitoring your applications is another aspect of managing code that developers must account for. Some things to consider would be:
- Security concerns
@ -280,7 +263,6 @@ Unleash was built with all these considerations in mind as part of our feature f
We make it easy to connect feature flag data, your application, and an analytics tool so you can collect, analyze, and report relevant data for your teams.
### Enable impression data events in Python
Let’s walk through how to enable impression data for the feature flag we created from the Python tutorial and capture the data in our app for analytics usage.
@ -289,7 +271,6 @@ At the flag level in Unleash, navigate to the Settings view.
![From your flag page in Unleash, you go to Settings and edit the settings for your flag called 'feature information'.](/img/python-ex-flag-settings.png)
In the Settings view, there's an edit button with pencil icon. This will take us to the ‘Edit Feature toggle’ form.
Turn on the impression data and then save it. Events will now be emitted every time the feature flag is triggered.
@ -328,15 +309,12 @@ You can use the impression events data from your flag and your strategy variants
You can find more information in our [impression data docs](/reference/impression-data#impression-event-data).
## Application Metrics & Monitoring for Python
Under your feature flag’s Metrics tab in Unleash, you can see the general activity of the [Flask Surveys Container App](/feature-flag-tutorials/python) tutorial in the development environment over different periods of time. If the app had a production environment enabled, we would also be able to view exposure (amount of users that are exposed to the flag by count and overall percentage) and requests the app is receiving over time.
![A Metrics graph provides the visualization of your flag being exposed in your environments for your connected application.](/img/python-ex-metrics.png)
Our metrics are great for understanding user traffic. You can get a better sense of:
- What time(s) of the day or week are requests the highest?
@ -346,10 +324,8 @@ Another use case for reviewing metrics is verifying that the right users are bei
Take a look at our [Metrics API documentation](/reference/api/unleash/metrics) to understand how it works from a code perspective.
## Feature Flag Audit Logs in Python
Because a feature flag service controls how 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, such as health care, insurance, banking, and others. In these cases (or similar), you might find audit logging useful for:
1. Organizational compliance
@ -363,10 +339,8 @@ For our Python app, we can view Event logs to monitor the changes to flag strate
- How the gradual rollout strategy was configured
- When and how the variants were created and configured
![Event logs in Unleash track every single change made to flags, similar to Git commit history.](/img/python-ex-logs.png)
You can also retrieve event log data by using an API command below:
```py
@ -385,15 +359,15 @@ response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
Read our documentation on [Event logs](/reference/event-log) and [APIs](/reference/api/unleash/get-events-for-toggle) to learn more.
## Flag Automation & Workflow Integration for Python Apps
An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. [Our Jira integration](/reference/integrations/jira-server-plugin-installation) helps to manage feature flag lifecycles associated with your projects.
An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. Our [Unleash Jira plugin](https://docs.getunleash.io/reference/integrations/jira-cloud-plugin-installation) helps to manage feature flag lifecycles associated with your projects.
It’s common for teams to have a development phase, QA/testing, and then a production release. Let’s say the changes we’ve made in our Python project must go through a typical development workflow. The [Unleash Jira plugin](https://marketplace.atlassian.com/apps/1227377/unleash-for-jira?tab=overview&hosting=datacenter) can connect to your Jira server or cloud to create feature flags automatically during the project creation phase. As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be Canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and/or roll out to target audiences in production.
It’s common for teams to have a development phase, QA/testing, and then a production release. Let’s say the changes we’ve made in our Python project must go through a typical development workflow.
As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be Canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and/or roll out to target audiences in production.
Here’s how this can be done via our API:
@ -464,45 +438,4 @@ Here’s how this can be done via our API:
Review [API docs on archiving flags](/reference/api/unleash/archive-feature).
## Common Usage Examples of Python Feature Flags
To fully utilize our Python SDK, we’ve compiled a list of the most common functions to call in a Python app.
| Method | Description | Parameters | Output |
| ------ | ----------- | ---------- | ------ |
| [`is_enabled`](#is_enabled-example) | determines whether or not the flag is enabled | feature flag name (string) | `True`, `False` (Boolean) |
| [`get_variant`](#get_variant-example) | returns the flag variant that the user falls into | feature flag name (string) | flag and variant data (object) |
| [`initialize_client`](#initialize_client-example) | starts UnleashClient | none | |
### `is_enabled` example
```py
flag = client.is_enabled(“feature_flag_name”)
return flag
# output
True
```
### `get_variant` example
```py
variant = client.get_variant(“feature_flag_name”)
return variant
# output
{'name': 'feature_flag_name', 'weightType': 'fix', 'enabled': True, 'feature_enabled': True}
```
### `initialize_client` example
```py
client = UnleashClient(
url="SERVER-SIDE API INSTANCE URL",
app_name="APP NAME",
custom_headers={'Authorization': '<API_TOKEN'})
client.initialize_client()
```
Learn more about different use cases in our [Python SDK documentation](/reference/sdks/python).

154
website/docs/feature-flag-tutorials/react/examples.md
View File

@ -7,20 +7,32 @@ In our [React tutorial](/feature-flag-tutorials/react), we implemented a simple
Applications evolve, and teams must manage all aspects of this evolution, including the flags used to control the application. We built multiple features into Unleash to address the complexities of releasing code and managing feature flags along the way:
1. [Gradual rollouts](#gradual-rollouts-for-react-apps)
2. [Canary deployments](#canary-deployments-in-react)
3. [A/B testing](#ab-testing-in-react)
4. [Feature flag metrics & reporting](#feature-flag-analytics-and-reporting-in-react)
5. [Feature flag audit logs](#feature-flag-audit-logs-in-react)
6. [Change management & feature flag approvals](#change-management--feature-flag-approvals-in-react)
7. [Flag automation & workflow integration](#flag-automation--workflow-integration-for-react-apps)
8. [Common usage examples of React feature flags](#common-usage-examples-of-react-feature-flags)
- [Gradual Rollouts for React Apps](#gradual-rollouts-for-react-apps)
- [Canary Deployments in React](#canary-deployments-in-react)
- [What is a canary deployment?](#what-is-a-canary-deployment)
- [Why use canary deployments?](#why-use-canary-deployments)
- [How to leverage feature flags for canary deployments in React?](#how-to-leverage-feature-flags-for-canary-deployments-in-react)
- [Configure strategy constraints for canary deployments](#configure-strategy-constraints-for-canary-deployments)
- [A/B Testing in React](#ab-testing-in-react)
- [Feature Flag Analytics and Reporting in React](#feature-flag-analytics-and-reporting-in-react)
- [Enable feature flag impression data](#enable-feature-flag-impression-data)
- [Capture impression data for flag analytics](#capture-impression-data-for-flag-analytics)
- [Application Metrics \& Monitoring](#application-metrics--monitoring)
- [Feature Flag Audit Logs in React](#feature-flag-audit-logs-in-react)
- [Change Management \& Feature Flag Approvals in React](#change-management--feature-flag-approvals-in-react)
- [Flag Automation \& Workflow Integration for React Apps](#flag-automation--workflow-integration-for-react-apps)
- [Common Usage Examples of React Feature Flags](#common-usage-examples-of-react-feature-flags)
- [`useFlag` example](#useflag-example)
- [`useVariant` example](#usevariant-example)
- [`useUnleashClient` example](#useunleashclient-example)
- [`useUnleashContext` example](#useunleashcontext-example)
- [`useFlags` example](#useflags-example)
- [`useFlagsStatus` example](#useflagsstatus-example)
- [Additional Examples](#additional-examples)
## Gradual Rollouts for React Apps
It’s common to use feature flags to roll out changes to a percentage of users. Flags allow you to monitor your application and infrastructure for undesired behavior (such as errors, memory bottlenecks, etc.) and to see if the changes improve the outcomes for your application (to increase sales, reduce support requests, etc.)
Doing a gradual rollout for a React-based application with Unleash is very straightforward. To see this in action, follow our [How to Implement Feature Flags in React](/feature-flag-tutorials/react) tutorial, which implements a notification feature using feature flags.
@ -29,16 +41,12 @@ Once you have completed the tutorial, you can modify the basic setup to adjust t
Navigate to the Gradual Rollout form in Unleash by using the "Edit strategy" button.
![The "edit strategy" button uses a pencil icon and is located on every strategy.](/img/react-ex-grad-rollout-edit.png)
Adjust the percentage of users to 50% or whichever value you choose, and refresh your app in the browser to see if your user has the new feature experience.
![A gradual rollout form can allow you to customize your flag strategy.](/img/ex-grad-rollout-form.png)
You can achieve this same result using our API with the following code:
```
@ -63,68 +71,54 @@ curl --location --request PUT 'http://localhost:4242/api/admin/projects/default/
Learn more about [gradual rollouts in our docs](/reference/activation-strategies.md).
## Canary Deployments in React
### What is a canary deployment?
Canary releases are a way to test and release code in different environments for a subset of your audience, which determines which features or versions of the platform people have access to.
### Why use canary deployments?
Canary deployments are a safer and more gradual way to make changes in software development. They help find any abnormalities and align with the agile process for faster releases and quick reversions.
### How to leverage feature flags for canary deployments in React?
Unleash has a few ways to help manage canary deployments for React apps at scale:
- Using a [gradual rollout](/reference/activation-strategies#gradual-rollout) (which we [implemented in a previous section](#gradual-rollouts-for-react-apps)) would be a simple use case but would reduce the amount of control you have over who gets the new feature.
* Using a [gradual rollout](/reference/activation-strategies#gradual-rollout) (which we [implemented in a previous section](#gradual-rollouts-for-react-apps)) would be a simple use case but would reduce the amount of control you have over who gets the new feature.
- Using either [constraints](/reference/strategy-constraints) or [segments](/reference/segments) (which are a collection of constraints) for a subset of your users to get the new feature vs. the old feature, for _more_ control than a gradual rollout
* Using either [constraints](/reference/strategy-constraints) or [segments](/reference/segments) (which are a collection of constraints) for a subset of your users to get the new feature vs. the old feature, for _more_ control than a gradual rollout
* [Strategy variants](/reference/strategy-variants) are used to do the same canary deployment, but can be scaled to more _advanced_ cases. For example, if you have 2+ new features and are testing to see if they are better than the old one, you can use variants to split your population of users and conduct an A/B test with them.
- [Strategy variants](/reference/strategy-variants) are used to do the same canary deployment, but can be scaled to more _advanced_ cases. For example, if you have 2+ new features and are testing to see if they are better than the old one, you can use variants to split your population of users and conduct an A/B test with them.
Let’s walk through how to utilize strategy constraints in our React app through the Unleash platform.
#### Configure strategy constraints for canary deployments
We will build a strategy constraint on top of our existing gradual rollout strategy. This will allow us to target a subset of users to rollout to.
In Unleash, start from the feature flag view and edit your Gradual Rollout strategy from your development environment.
![Configure your gradual rollout strategy with a constraint.](/img/react-ex-grad-rollout-edit.png)
This will take you to the gradual rollout form. Click on the ‘Add constraint’ button.
![You can add a constraint to your flag in the constraints form.](/img/react-ex-add-constraint-btn.png)
Let’s say we are experimenting with releasing the notifications feature for a limited time. We want to release it to **all users**, capture some usage data to compare it to the old experience, and then automatically turn it off.
We can configure the constraint in the form to match these requirements:
![A constraint form has a context field and operator with options to base your context field off of.](/img/react-ex-constraint-form.png)
* The context field is set to **currentTime**
* The operator is set to **DATE_BEFORE**
* The date time is set to any time in the future
- The context field is set to **currentTime**
- The operator is set to **DATE_BEFORE**
- The date time is set to any time in the future
Once you’ve filled out the proper constraint fields, click ‘Done’ and save the strategy.
![Your strategy has a constraint saved to it.](/img/react-ex-rollout-with-constraint.png)
Your release process is now configured with a datetime-based strategy constraint.
Alternatively, you can send an API command to apply the same requirements:
@ -159,10 +153,8 @@ curl --location --request PUT 'http://localhost:4242/api/admin/projects/default/
Read our documentation for more context on the robustness of [strategy constraint configurations](/reference/strategy-constraints) and use cases.
## A/B Testing in React
A/B testing is a common way for teams to test out how users interact with two or more versions of a new feature that is released. At Unleash, we call these [variants](/reference/feature-toggle-variants).
We can expose a particular version of the 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.
@ -173,24 +165,18 @@ In the context of our [React tutorial](/feature-flag-tutorials/react), we have a
In Unleash, navigate to the feature flag’s Variants tab and add a variant.
![We point to the button in Unleash to add a variant, labeled "add variant".](/img/react-ex-add-variant.png)
In the Variants form, add two variants that will reference the different icons we will render in our app. Name them ‘notificationsIcon’ and ‘announcementsIcon’.
Note: We won’t use any particular payload from these variants other than their default returned objects. For this example, we can keep the variant at 50% weight for each variant, meaning there is a 50% chance that a user will see one icon versus the other. You can adjust the percentages based on your needs, such as making one icon a majority of users would see by increasing its weight percentage. Learn more about [feature flag variant properties](/reference/feature-toggle-variants).
![The form allows you to configure your variant.](/img/react-ex-variant-form.png)
Once you click 'Save variants' at the bottom of the form, your view will display the list of variants in the development environment with their respective metadata.
![Your feature flag view shows that a variant has been added.](/img/react-ex-variant-added.png)
Alternatively, we can create new variants via an API command below:
```
@ -215,15 +201,12 @@ Now that we have configured our feature flag variants, we can reference them in
In `NavBar.tsx`, import the Announcements icon at the top of the file from Material UI, just like the Notifications icon.
```js
Announcement as AnnouncementsIcon,
```
The full import line now looks like this:
```js
import {
Menu as MenuIcon,
@ -233,23 +216,20 @@ import {
} from "@material-ui/icons";
```
Unleash has a built-in React SDK hook called [useVariant](/reference/sdks/react#check-variants) to retrieve variant data and perform different tasks against them.
Next, import the `useVariant` hook from the React SDK:
```js
import { useFlag, useVariant } from "@unleash/proxy-client-react";
```
`useVariant` returns the name of the specific flag variant your user experiences, if it’s enabled, and if the overarching feature flag is enabled as well.
Within the `NavBar` component itself, we will:
* Reference the flag that holds the variants
* Reference the two variants to conditionally check that their enabled status for rendering
- Reference the flag that holds the variants
- Reference the two variants to conditionally check that their enabled status for rendering
Next, we can modify what is returned in the `NavBar` component to account for the two variants the user might see on render.
@ -257,22 +237,17 @@ Previously, we toggled the `NotificationsIcon` component based on whether or not
With our new variants implemented, 50% of users will see the announcements icon. The differences in the UI would look like this:
![We can compare two variations of an icon in the app browser.](/img/react-ex-compare-icons.png)
We have successfully configured our flag variants and implemented them into our React app for A/B testing in our development environment. Next, we can take a look at how Unleash can track the results of A/B testing and provide insights with data analytics.
## Feature Flag Analytics and Reporting in React
Shipping code is one thing, but monitoring our applications is another thing we all have to account for. Some things to consider would be:
* Security concerns
* Performance metrics
* Tracking user behavior
- Security concerns
- Performance metrics
- Tracking user behavior
Unleash was built with all of these considerations in mind as part of our feature flag management approach. You can use feature flag events to send impression data to an analytics tool you choose to integrate. For example, a new feature you’ve released could be causing more autoscaling in your service resources than expected and you either can view that in your Analytics tool or get notified from a Slack integration. Our impression data gives developers a full view of the activity that could raise any alarms.
@ -280,21 +255,16 @@ We make it easy to get our data, your application, and an analytics tool connect
Let’s walk through how to enable impression data for the feature flag we created from the React tutorial and capture the data in our app for analytics usage.
### Enable feature flag impression data
At the flag level in Unleash, navigate to the Settings view.
![Editing feature flag settings in Unleash.](/img/react-ex-edit-settings.png)
In the Settings view, click on the edit button. This will take us to the ‘Edit Feature toggle’ form.
![Enabling impression data for a feature flag.](/img/react-ex-enable-impression-data.png)
Turn on the impression data and hit ‘Save’. Events will now be emitted every time the feature flag is triggered.
You can also use our API command to enable the impression data:
@ -319,7 +289,11 @@ Next, let’s configure our React app to capture the impression events that are
In `NavBar.tsx`, pull in `useUnleashClient`. Our updated import line should look like this:
```js
import { useFlag, useVariant, useUnleashClient } from "@unleash/proxy-client-react";
import {
useFlag,
useVariant,
useUnleashClient,
} from "@unleash/proxy-client-react";
```
Next, within the `NavBar` component itself, call `useUnleashClient` and wrap a `useEffect` hook around our function calls to grab impression data with this code snippet:
@ -331,7 +305,9 @@ Next, within the `NavBar` component itself, call `useUnleashClient` and wrap a `
unleashClient.start();
unleashClient.on("ready", () => {
const enabledImpression = unleashClient.isEnabled("newNotificationsBadge");
const enabledImpression = unleashClient.isEnabled(
"newNotificationsBadge"
);
console.log(enabledImpression);
});
@ -387,32 +363,25 @@ You can find more information on `isEnabled` and `getVariant` in our [impression
Now that the application is capturing impression events, you can configure the correct data fields and formatting to send to any analytics tool or data warehouse you use.
### Application Metrics & Monitoring
Under the Metrics tab, you can see the general activity of the [Cypress Real World App from our React tutorial](/feature-flag-tutorials/react) in the development environment over different periods of time. If the app had a production environment enabled, we would also be able to view the amount of exposure and requests the app is receiving over time.
![We have a Metrics graph in Unleash to review flag exposure and request rates.](/img/react-ex-metrics.png)
Our metrics are great for understanding user traffic. You can get a better sense of:
* What time(s) of the day or week are requests the highest?
* Which feature flags are the most popular?
- What time(s) of the day or week are requests the highest?
- Which feature flags are the most popular?
Another use case for reviewing metrics is verifying that the right users are being exposed to your feature based on how you’ve configured your strategies and/or variants.
Take a look at our [Metrics API documentation](/reference/api/unleash/metrics) to understand how it works from a code perspective.
## Feature Flag Audit Logs in React
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, such as health care, insurance, banking, and others. In these cases (or similar), you might find audit logging useful for:
1. Organizational compliance
2. Change control
@ -422,15 +391,12 @@ Unleash provides the data to log any change that has happened over time, at the
In our React tutorial application, we can view Event logs to monitor the changes to flag strategies and statuses we have made throughout our examples, such as:
* When the `newNotificationsBadge` flag was created
* How the gradual rollout strategy was configured
* When and how the variants were created and configured
- When the `newNotificationsBadge` flag was created
- How the gradual rollout strategy was configured
- When and how the variants were created and configured
![Feature flag event log. The flag's variant's have been updated.](/img/react-ex-event-log.png)
You can also retrieve event log data by using an API command below:
```
@ -441,37 +407,32 @@ curl -L -X GET '<your-unleash-url>/api/admin/events/:featureName' \
Read our documentation on [Event logs](/reference/event-log) and [APIs](/reference/api/unleash/events) to learn more.
## Change Management & Feature Flag Approvals in React
Unleash makes it easy to toggle a feature. But the more users you have, the more risk with unexpected changes occurring. That’s why we implemented an approval workflow within Unleash Enterprise for making a change to a feature flag. This functions similar to GitHub's pull requests, and models a Git review workflow. You could have one or more approvals required to reduce risk of someone changing something they shouldn’t. It helps development teams to have access only to what they _need_. For example, you can use Unleash to track changes to your React feature flag’s configuration.
In Unleash Enterprise, we have a change request feature in your project settings to manage your feature flag approvals. When someone working in a project needs to update the status of a flag or strategy, they can follow our approval workflow to ensure that one or more team members review the change request.
![Change request configuration page under project settings.](/img/react-ex-project-settings.png)
We have several statuses that indicate the stages a feature flag could be in as it progresses through the workflow. This facilitates collaboration on teams while reducing risk in environments like production. For larger scale change management, you can ensure the correct updates are made while having full visibility into who made the request for change and when.
![Change request waiting for approval. Disables flag CR-toggle-3.](/img/react-ex-change-requests.png)
Learn more about [how to configure your change requests](/reference/change-requests) and our [project collaboration mode](/reference/project-collaboration-mode).
## Flag Automation & Workflow Integration for React Apps
An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. [Our Jira integration](/reference/integrations/jira-server-plugin-installation) helps to manage feature flag lifecycles associated with your projects.
An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. Our [Unleash Jira plugin](https://docs.getunleash.io/reference/integrations/jira-cloud-plugin-installation) helps to manage feature flag lifecycles associated with your projects.
Let’s say the changes we’ve made in our React tutorial project need to go through a typical development workflow. The [Unleash Jira plugin](https://marketplace.atlassian.com/apps/1227377/unleash-for-jira?tab=overview&hosting=datacenter) can connect to your Jira server or cloud to create feature flags automatically during the project creation phase. As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and rollout and/or rollout to target audiences in production.
Let’s say the changes we’ve made in our React tutorial project need to go through a typical development workflow.
As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and rollout and/or rollout to target audiences in production.
You can write your own integration to your own ticketing tool if you don't use Jira. And [join our Slack](https://slack.unleash.run/) to discuss this if you're not sure how to proceed.
Here’s how this can be done via our API:
1. Enable a flag.
```
@ -509,6 +470,7 @@ Here’s how this can be done via our API:
"impressionData": false
}
```
Review our [API docs on updating feature flags](/reference/api/unleash/update-feature).
3. Archive a flag.
@ -520,15 +482,14 @@ Here’s how this can be done via our API:
Review [API docs on archiving flags](/reference/api/unleash/archive-feature).
## Common Usage Examples of React Feature Flags
To take full advantage of our React SDK, we’ve compiled a list of the most common functions to call in a React app.
| Function | Description | Parameters | Output |
| -------- | ----------- | ---------- | ------ |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------- |
| [`useFlag`](#useflag-example) | determines whether or not the flag is enabled | feature flag name (string) | true, false (boolean) |
| [`useVariant`](#usevariant-example)| returns the flag variant that the user falls into| feature flag name (string)| flag and flag variant data (object)
| [`useVariant`](#usevariant-example) | returns the flag variant that the user falls into | feature flag name (string) | flag and flag variant data (object) |
| [`useUnleashClient`](#useunleashclient-example) | listens to client events and performs actions against them | none | |
| [`useUnleashContext`](#useunleashcontext-example) | retrieves information related to current flag request for you to update | none | |
| [`useFlags`](#useflags-example) | retrieves a list of all flags within your project | none | an array of each flag object data |
@ -591,19 +552,19 @@ const allFlags = useFlags();
// output
[
{
name: 'string',
name: "string",
enabled: true,
variant: {
name: 'string',
name: "string",
enabled: false,
},
impressionData: false,
},
{
name: 'string',
name: "string",
enabled: true,
variant: {
name: 'string',
name: "string",
enabled: false,
},
impressionData: false,
@ -620,7 +581,6 @@ const flagsStatus = useFlagsStatus();
{ flagsReady: true, flagsError: null }
```
## Additional Examples
Many additional use cases exist for React, including [deferring client start](/reference/sdks/react#deferring-client-start), [usage with class components](/reference/sdks/react#usage-with-class-components), [React Native](/reference/sdks/react#react-native), and more, all of which can be found in our [React SDK documentation](/reference/sdks/react).

46
website/docs/feature-flag-tutorials/ruby/ruby-examples.md
View File

@ -18,10 +18,6 @@ We built many features into Unleash, our open-source feature flag platform, to a
- [Application Metrics \& Monitoring for Ruby apps](#application-metrics--monitoring-for-ruby-apps)
- [Feature Flag Audit Logs in Ruby](#feature-flag-audit-logs-in-ruby)
- [Flag Automation \& Workflow Integration for Ruby Apps](#flag-automation--workflow-integration-for-ruby-apps)
- [Common Usage Examples for Ruby Feature Flags](#common-usage-examples-for-ruby-feature-flags)
- [`is_enabled` example](#is_enabled-example)
- [`get_variant` example](#get_variant-example)
- [Initialization](#initialization)
> Note:
> We're using the `httpx` gem to make sending requests easier.
@ -221,7 +217,6 @@ Next, we can examine how Unleash can track the results and provide insights with
Shipping code is one thing, but monitoring your applications is another aspect of managing code to account for. Some things to monitor could be:
- Security vulnerabilities
- Performance metrics
- Tracking user behavior
@ -331,7 +326,7 @@ Read our documentation on [Event logs](/reference/event-log) and [APIs](/referen
An advanced use case for leveraging feature flags at scale is automating them as part of your development workflow.
It’s common for teams to have a development phase, then QA/testing, and then a production release. Our [Unleash Jira plugin](https://marketplace.atlassian.com/apps/1227377/unleash-for-jira?tab=overview&hosting=datacenter) can connect to your Jira server or cloud to create feature flags automatically during the project phases.
It’s common for teams to have a development phase, then QA/testing, and then a production release. Our [Unleash Jira plugin](https://docs.getunleash.io/reference/integrations/jira-cloud-plugin-installation) can connect to your Jira server or cloud to create feature flags automatically during the project phases.
As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be Canary deployments for testing with certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and/or rolled out to target audiences in production.
@ -399,43 +394,4 @@ Here’s how this can be done via our API:
Review [API docs on archiving flags](/reference/api/unleash/archive-feature).
## Common Usage Examples for Ruby Feature Flags
We’ve compiled a list of the most common functions to call with our Ruby SDK.
| Method | Description | Parameters | Output |
| ------------------------------------------------- | ------------------------------------------------- | -------------------------- | ------------------------------ |
| [`is_enabled`](#is_enabled-example) | determines whether or not the flag is enabled | feature flag name (string) | `True`, `False` (Boolean) |
| [`get_variant`](#get_variant-example) | returns the flag variant that the user falls into | feature flag name (string) | flag and variant data (object) |
| [`initialize_client`](#initialize_client-example) | starts UnleashClient | none | |
### `is_enabled` example
```ruby
flag = client.is_enabled?("feature_flag_name")
return flag
# output
true
```
### `get_variant` example
```ruby
variant = client.get_variant?("feature_flag_name")
return variant
# output
{'name': 'feature_flag_name', 'weightType': 'fix', 'enabled': true, 'feature_enabled': true}
```
### Initialization
```ruby
client = Unleash::Client.new(
url="<your-unleash-url>",
app_name="APP NAME",
custom_http_headers:{'Authorization': '<API_TOKEN>'})
```
Learn more about different use cases in our [Ruby SDK documentation](/reference/sdks/ruby).

6
website/docs/reference/integrations/jira-server-plugin-installation.md
View File

@ -2,7 +2,11 @@
title: Jira Server Integration - Installation
---
> The Jira Server Plugin is part of Unleash Enterprise.
:::info Deprecated
The Jira Server plugin is **deprecated**, please use the [Unleash Jira Cloud plugin](https://docs.getunleash.io/reference/integrations/jira-cloud-plugin-installation) instead
:::
With the Unleash Jira server plugin you can create new feature toggles in Unleash from a Jira issue as well as link
existing toggles to Jira issues.

6
website/docs/reference/integrations/jira-server-plugin-usage.md
View File

@ -2,7 +2,11 @@
title: Jira Server Integration - Usage
---
> The Jira Server Plugin is part of Unleash Enterprise.
:::info Deprecated
The Jira Server plugin is **deprecated**, please use the [Unleash Jira Cloud plugin](https://docs.getunleash.io/reference/integrations/jira-cloud-plugin-installation) instead
:::
With the Unleash Jira server plugin you can create new feature toggles in Unleash from a Jira issue as well as link
existing toggles to Jira issues.