Merge pull request #1440 from Unleash/docs/how-to-time-feature-releases

docs: add how to schedule feature releases guide

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. `<placeholder-name>`). 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"`.
+
+<ApiRequest verb="post" payload={{
+      "name": "default",
+      "constraints": [
+        {
+          "value": "<activation-date>",
+          "operator": "DATE_AFTER",
+          "contextName": "currentTime"
+        }
+      ]
+  }} url="api/admin/projects/<project-id>/features/environments/<environment>/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).

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: {