d5fbd0b743
## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
6.3 KiB
| title |
|---|
| How to create a feature toggle |
Feature toggles are the foundation of Unleash. They are at the core of everything we do and are a fundamental building block in any feature management system. This guide shows you how to create feature toggles in Unleash and how to add any optional constraints, segments, variants, and more. Links to learn more about these concepts will be scattered throughout the text.
You can perform every action both via the UI and the admin API. This guide includes screenshots to highlight the relevant UI controls and links to the relevant API methods for each step.
This guide is split into three sections:
- Prerequisites: you need these before you can create a toggle.
- Required steps: all the required steps to create a toggle and activate it in production.
- Optional steps: optional steps you can take to further target and configure your feature toggle and its audience.
Prerequisites
To be able to create a feature toggle in an Unleash system you will need:
- A running Unleash instance
- A project to hold the toggle
- A user with an editor or admin role OR a user with the following permissions inside the target project:
- create feature toggles
- create/edit variants
- create activation strategies (for the right environment)
- update activation strategies (for the right environment)
- enable/disable toggles (for the right environment)
:::info roles
Refer to the documentation on role-based access control for more information about the available roles and their permissions.
:::
Required steps
This section takes you through the required steps to create and activate a feature toggle. It assumes that you have all the prerequisites from the previous section done.
Step 1: Create a toggle
:::tip API: create a toggle
Use the Admin API endpoint for creating a feature toggle. The payload accepts all the same fields as the Admin UI form. The Admin UI also displays the corresponding cURL command when you use the form.
:::
In the project that you want to create the toggle in, use the "new feature toggle" button and fill the form out with your desired configuration. Refer to the feature toggle reference documentation for the full list of configuration options and explanations.
Step 2: Add a strategy
:::tip API: Add a strategy
Use the API for adding a strategy to a feature toggle. You can find the configuration options for each strategy in the activation strategy reference documentation.
:::
Decide which environment you want to enable the toggle in. Select that environment and add an activation strategy. Different activation strategies will act differently as described in the activation strategy documentation. The configuration for each strategy differs accordingly. After selecting a strategy, complete the steps to configure it.
Step 3: Enable the toggle
:::tip API: Enable a toggle
Use the API for enabling an environment for a toggle and specify the environment you'd like to enable.
:::
Use the environments toggles to switch on the environment that you chose above. Depending on the activation strategy you added in the previous step, the toggle should now evaluate to true or false depending on the Unleash context you provide it.
Optional steps
These optional steps allow you to further configure your feature toggles to add optional payloads, variants for A/B testing, more detailed user targeting and exceptions/overrides.
Add constraints and segmentation
Constraints and segmentation allow you to set filters on your strategies, so that they will only be evaluated for users and applications that match the specified preconditions. Refer to the strategy constraints and segments reference documentation for more information.
To add constraints and segmentation, use the "edit strategy" button for the desired strategy.
Constraints
:::info
Constraints aren't fixed and can be changed later to further narrow your audience. You can add them either when you add a strategy to a toggle or at any point thereafter.
:::
:::tip API: Add constraints
You can either add constraints when you add the strategy or PUT or PATCH the strategy afterwards
:::
In the strategy configuration screen for the strategy that you want to configure, use the "add constraint" button to add a strategy constraint.
Segments
:::info
This can be done after you have created a strategy.
:::
:::tip API: add segments
Use the API for adding segments to a strategy to add segments to your strategy.
:::
In the strategy configuration screen for the strategy that you want to configure, use the "select segments" dropdown to add segments.
Add variants
:::info
This can be done at any point after you've created your toggle.
:::
:::tip API: add variants
Use the update variants endpoint. The payload should be your desired variant configuration.
:::
Variants give you the ability to further target your users and split them into groups of your choosing, such as for A/B testing. On the toggle overview page, select the variants tab. Use the "new variant" button to add the variants that you want.
