diff --git a/website/docs/how-to/how-to-schedule-feature-releases.mdx b/website/docs/how-to/how-to-schedule-feature-releases.mdx new file mode 100644 index 00000000000..eed3a00b94e --- /dev/null +++ b/website/docs/how-to/how-to-schedule-feature-releases.mdx @@ -0,0 +1,84 @@ +--- +title: How to schedule feature releases +--- +import ApiRequest from '@site/src/components/ApiRequest' + +:::info Placeholders +Placeholders in the code samples below are delimited by angle brackets (i.e. ``). You will need to replace them with the values that are correct in _your_ situation for the code samples to run properly. +::: + +There's a whole host of reasons why you may want to schedule the release of a feature, such as: +- **to release a feature at a specific date and time** (for a product launch, for instance) +- **to make a feature available only up until a specific moment** (for a contest cutoff, for instance) +- **to make a feature available during a limited period** (for a 24 hour flash sale, for instance) + +There's two distinct ways to do this, depending on which version of Unleash you are running: +- If you're using version 4.9 or later of Unleash Pro or Enterprise, you can (and should) [use strategy constraints](#strategy-constraints) +- Otherwise, [use custom activation strategies](#custom-activation-strategies) + +In this guide we'll schedule a feature for release at some point in time. The exact same logic applies if you want to make a feature available until some point in the future. Finally, if you want to only make a feature available during a limited time period, you can easily combine the two options. + +## Prerequisites + +This guide assumes that you've got the following: +- some basic experience with Unleash +- a running instance of Unleash and connected clients (where applicable) +- an existing feature toggle that you want to schedule the release for + +## Schedule feature releases with strategy constraints {#strategy-constraints} + +You can use this approach with _any_ strategy you want. The strategies will work just as they normally do, they just won't become active until the specified time. For example: with the standard strategy, the feature would become available to all your users at the specified time; with a gradual rollout, the rollout would start at the specified time. + +### Step 1: Add an activation strategy with a date-based constraint + +#### Scheduling a release via the UI + +To schedule a feature release via the UI: +1. Add the desired activation strategy to the feature +2. Open the constraint creator by using the "add constraint" button +3. Add a date-based constraint by selecting the `currentTime` context field (step 1 in the below image), choosing the `DATE_AFTER` operator (step 2), and setting the point in time where you want the feature to be available from (step 3) + ![A strategy constraint specifying that the activation strategy should be enabled at 12:00 AM, November 25th 2022. There are visual call-outs pointing to the relevant settings mentioned above.](/img/strategy-constraint-date-after.png) + +#### Scheduling a release via the API + +To add an activation strategy via the Admin API, use the feature's `strategies` endpoint to add a new strategy (see the [API documentation for adding strategies to feature toggles](../api/admin/feature-toggles-api-v2.md#add-strategy) for more details). + +The payload's `"name"` property should contain the name of the strategy to apply (see [activation strategies reference documentation](../user_guide/activation-strategies.md) for all built-in strategies' _modeling names_). + +The `"constraint"` object should have the same format as described in the code sample below. The activation date must be in an [RFC 3339-compatible format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.8), e.g. `"1990-12-31T23:59:60Z"`. + +", + "operator": "DATE_AFTER", + "contextName": "currentTime" + } + ] + }} url="api/admin/projects//features/environments//strategies" title="Add a feature activation strategy with a scheduled activation time."/> + +The `"operator"` property in the code sample can be replaced with [any of the other date and time-based operators](../advanced/strategy-constraints.md#date-and-time-operators) according to your needs. + +## Schedule feature releases with custom activation strategies {#custom-activation-strategies} + +To schedule feature releases without using strategy constraints, you can use custom activation strategies. This requires defining a custom strategy and then implementing that strategy in your SDKs. For detailed instructions on how to do either of these things, refer to their respective how-to guides: +- [How to _define_ custom strategies](../how-to/how-to-use-custom-strategies.md#step-1) +- [How to _implement_ custom strategies](../how-to/how-to-use-custom-strategies.md#step-3) + +### Step 1: Define and apply a custom activation strategy + +**Define a strategy** that takes a parameter that tells it when to activate (visit [the custom activation strategy reference documentation](../advanced/custom-activation-strategy.md#definition) for full details on definitions): + +1. Give the strategy a name. We'll use `enableAfter`. +2. Give the strategy a required string parameter where the user can enter the time at which the feature should activate. Be sure to describe the format that the user must adhere to. +3. Save the strategy + +[**Apply the strategy** to the feature toggle](../how-to/how-to-use-custom-strategies.md#step-2) you want to schedule. + + +![A custom activation strategy definition for a strategy called `enableAfter`. It takes a required parameter called `start time`: a string in a date format.](/img/custom-strategy-enable-after.png) + +### Step 2: Implement the custom activation strategy in your clients + +In each of the client SDKs that will interact with your feature, implement the strategy ([the implementation how-to guide](../how-to/how-to-use-custom-strategies.md#step-3) has steps for all SDK types). diff --git a/website/sidebars.js b/website/sidebars.js index de1844eacb6..a5c0f86f938 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -54,10 +54,11 @@ module.exports = { label: 'Feature toggles, strategies, context', items: [ 'how-to/how-to-add-strategy-constraints', + 'how-to/how-to-capture-impression-data', 'user_guide/create_feature_toggle', 'how-to/how-to-define-custom-context-fields', 'how-to/how-to-use-custom-strategies', - 'how-to/how-to-capture-impression-data' + 'how-to/how-to-schedule-feature-releases', ], type: 'category', link: { diff --git a/website/static/img/custom-strategy-enable-after.png b/website/static/img/custom-strategy-enable-after.png new file mode 100644 index 00000000000..a42b0af65cb Binary files /dev/null and b/website/static/img/custom-strategy-enable-after.png differ diff --git a/website/static/img/strategy-constraint-date-after.png b/website/static/img/strategy-constraint-date-after.png new file mode 100644 index 00000000000..fed8893cdfe Binary files /dev/null and b/website/static/img/strategy-constraint-date-after.png differ