diff --git a/docs/best-practices/lifecycle.mdx b/docs/best-practices/lifecycle.mdx new file mode 100644 index 00000000..1ff12479 --- /dev/null +++ b/docs/best-practices/lifecycle.mdx @@ -0,0 +1,109 @@ +--- +title: Feature Flags Lifecycles +slug: /best-practices/feature-flag-lifecycle +description: Describe the feature flag lifecycle types and the best practices on how to use them. +tags: ['best-practices', 'lifecycle'] +--- + +import CenteredImg from '@site/src/components/centered-img/CenteredImg'; + +It's crucial to regularly manage your code to prevent the accumulation of outdated, unused flags in your application. This guide shows a straightforward approach using Bucketeer to determine [when to archive](/best-practices/feature-flag-lifecycle#when-archive-a-flag) and remove feature flags from your application. + +## When archive a flag + +In Bucketeer, a flag can have one of the following status: + +- **New**: Recently created flags with no requests received. +- **Receiving requests**: Active flags that have received requests within the last 7 days. +- **Inactive**: Flags that haven't received requests for over 7 days. It's important to note that both ON and OFF flags can become inactive. + + + +You can use the flag status information as a reference to archive the flag and remove its code from your application. An inactive flag in your dashboard signals that it's no longer in use and can be archived. + +### Why archive flags? + +Archiving inactive flags is crucial for optimizing resource usage and improving user experience. Inactive flags that continue being sent to clients, increasing: + +- The size of server repose and cache on the client. +- The response latency. + +Inactive flags mainly affect the application startup process for new users or users with no cache. + +:::info Flag evaluation + +Keep in mind that Bucketeer does not reevaluate previously evaluated flags unless specific conditions are met: + +- New user access. +- Cache clearance by existing users. +- Application with no activities over 30 days. + +::: + +### How to archive a flag + +The Bucketeer team recommends the following steps for inactive flags: + +1. Remove the flag code from your application. +2. Access the **Feature Flag** list page. +3. Click the inactive flag's action button (**...**) and select **Archive**. +4. Provide a comment for the update, then click **Submit**. + + + +:::note Archiving warning + +The Bucketeer system will warn you if the flag has received at least one request in the last 7 days. + +::: + +:::info Remove flag code first + +Archiving a flag that persists in your code will make your application use the default value defined in your code. This behavior happens for different reasons whether you use a client or server SDK: + +- **Server SDK**: Results in a not-found error from the Bucketeer server, making your code use the default values defined in your application. +- **Client SDK**: Your application won't find the variation in its cache, making your code use the default values. + +::: + +## Flag lifecycle + +Feature flags are often used temporarily to reduce risks of new features during release, with a short lifecycle. Once the rollout is complete, you should remove the flag from the code and archive it on the dashboard. + +The flag lifecycle shows how feature flags are used across different development stages, categorized into two main types. + +- **Temporary**: Flags are removed from the application and archived when they're no longer active. +- **Permanent**: Flags are kept even when inactive for some time, as they're not used continuously. + + +### Temporary Flags + +Typically, you'll use temporary flags for the following purposes: + +- **Feature rollouts**: Used to decouple feature deployment from release. Once the feature is fully deployed and tested, the flag is removed from the code and archived on the dashboard. +- **Experimentation**: Used for A/B testing and multivariate experiments. Once the experiment finishes, the flag is removed from the code and archived on the dashboard. + +### Permanent Flags + +Other applications may require flags to be used longer, sometimes for the same application lifetime. As a result, permanent flags have longer lifecycles and fulfill ongoing needs: + +- **Kill switches**: Remove or add features or entire application sections, often used during deployments or downtime. These flags remain permanent for quick action in unexpected situations. +- **Feature management flags**: Used for controlling feature availability based on user segments or traits. These flags remain throughout the application's lifetime to manage platform features for specific user groups. + +#### Examples of permanent flag use cases + +A typical scenario of a permanent flag is related to mobile apps prompting users to update their version. Such a request is usually used in situations like the release of unfinished features or if your app is frequently crashing. By incorporating a permanent boolean flag within the app's code, developers can control when the update prompt appears. Once set to true, the flag triggers a pop-up requesting the app update. + +Another example of a permanent flag is reusing it to run multiple tests. While repurposing a flag isn't ideal and might seem like it loses its original purpose, in some cases, it's better than constantly asking users to update the app. Plus, it saves time by bypassing the slow application review process in the Google and Apple Store. + +The reuse of flags is adopted because when working with client applications, you can't define when your user updates the application. As a result, you can only sometimes rely on feature flags from the last release. Therefore, you can have a fixed flag in your application to execute common actions such as: + +- Test algorithms. +- Change the algorithms used in searches. +- Change a banner's URL in your application. \ No newline at end of file diff --git a/docs/feature-flags/creating-feature-flags/create-feature-flag.md b/docs/feature-flags/creating-feature-flags/create-feature-flag.md index 4d218c48..d65fa143 100644 --- a/docs/feature-flags/creating-feature-flags/create-feature-flag.md +++ b/docs/feature-flags/creating-feature-flags/create-feature-flag.md @@ -43,6 +43,18 @@ Once you have created a flag, it will automatically appear on the **Feature Flag You can duplicate and archive flags as well. To perform these actions, click the three-dot button on the desired flag. +:::info Feature flag status + +Feature flags may have one of the following three statuses: + +- **New**: A recently created flag that hasn't yet received any request. +- **Receiving requests**: Active flags that have received requests within the last 7 days. +- **Inactive**: Flags that haven't received requests for over 7 days. It's important to note that both ON and OFF flags can become inactive. + +The flag status helps identify the lifecycle stage of your flag, indicating if it's time to archive it. Access the [feature flag lifecycle page](/best-practices/feature-flag-lifecycle) to learn more about the best practices for the flag's usage. + +::: + :::tip When a flag is archived, any SDK requests related to that flag will return the default value, typically the value associated with the **OFF** state. To ensure proper functionality, we recommend removing flag evaluations from your code when archiving the flag in the Bucketeer system. diff --git a/sidebars.js b/sidebars.js index f5ba3d1e..e5e39435 100644 --- a/sidebars.js +++ b/sidebars.js @@ -213,6 +213,11 @@ const sidebars = { label: 'Optimize with Tags', className: 'sidebar-contributing', }, + { + type: 'doc', + id: 'best-practices/lifecycle', + className: 'sidebar-contributing', + }, { type: 'html', value: "Contribution", diff --git a/static/img/best-practices/archive-flag.png b/static/img/best-practices/archive-flag.png new file mode 100644 index 00000000..b4229560 Binary files /dev/null and b/static/img/best-practices/archive-flag.png differ diff --git a/static/img/best-practices/flag-status.png b/static/img/best-practices/flag-status.png new file mode 100644 index 00000000..b92d66dd Binary files /dev/null and b/static/img/best-practices/flag-status.png differ