New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add how to schedule feature releases guide #1440
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
27a74ec
docs: create initial outline for how to schedule feature releases
thomasheartman 8c56579
docs: add more placeholder / structural content.
thomasheartman 905fa6f
docs: create first draft of schedule how-to
thomasheartman b3faf3e
docs: add screenies and update descriptions accordingly
thomasheartman 0a34661
docs: clear up that constraints are available to pro customers too
thomasheartman File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Complete and utter nitpick but sometimes we use capitalised first letters in lists in this page and sometimes we don't, might be cleaner if we stick to one style unless there's overriding reasons to mix styles
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Totally agree that it would be cleaner! This is already merged in now, but I'll keep that in mind going forward. It does depend a bit on the context (I think), though. E.g.:
I want to ...
Unleash has a number of security mechanisms built in:
But maybe standardizing on always capitalizing would work well, now that I think about it 🤔 Great input either way!