docs: Trunk-based development use case tutorial #8867
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.OpenSSF Scorecard
Scanned Files |
|
|
||
| Some of the most appropriate feature candidates for trunk-based development are features with significant potential impact on users that may require thorough testing. | ||
|
|
||
| In TBD, developers merge incomplete code into the main branch. Unleash feature flags allow this to happen safely by keeping the feature hidden or disabled, ensuring the trunk remains in a releasable state. The flag starts as “off” in production while the feature is incomplete. The flag can be on in development and/or a testing environment until the feature is complete and ready to go live in production for all users. |
There was a problem hiding this comment.
@sighphyre @melindafekete thoughts on using the acronym vs. just using "trunk-based development" once the term has been referenced many times already in the doc?
There was a problem hiding this comment.
OMG so many TLAs TBH
Seriously though, I think that's fine. From a quick Google search, it seems like all the cool kids are doing that these days
I'm a fan of introducing it once with the acronym - trunk based development (TBD) and then just using the acronym going forwarda
There was a problem hiding this comment.
I'm not familiar with this acronym for trunk-based development. Makes me think of 'to be determined' which is very common. I would be concerned about causing more confusion than the amount of time it saves when reading
There was a problem hiding this comment.
I'm not familiar with this acronym
Also had to Google it
|
|
||
| Some of the most appropriate feature candidates for trunk-based development are features with significant potential impact on users that may require thorough testing. | ||
|
|
||
| In TBD, developers merge incomplete code into the main branch. Unleash feature flags allow this to happen safely by keeping the feature hidden or disabled, ensuring the trunk remains in a releasable state. The flag starts as “off” in production while the feature is incomplete. The flag can be on in development and/or a testing environment until the feature is complete and ready to go live in production for all users. |
There was a problem hiding this comment.
OMG so many TLAs TBH
Seriously though, I think that's fine. From a quick Google search, it seems like all the cool kids are doing that these days
I'm a fan of introducing it once with the acronym - trunk based development (TBD) and then just using the acronym going forwarda
| - Increased need for effective merging strategies | ||
| - Requirement for robust automated testing and CI/CD pipelines | ||
|
|
||
| ### Merge at Set Intervals |
There was a problem hiding this comment.
I've never heard of anyone advocating this. Not a challenge, just curious who's going this route, this sounds really painful!
Edit: I see Atlassian is recommending this, which explains why I think that's crazy
| - Potential for larger, more complex merges | ||
| - Requires discipline to adhere to the defined merge cadence | ||
|
|
||
| ### Benefits of Short-Lived Feature Branches |
There was a problem hiding this comment.
This is 100% a personal feeling so take it for what it's worth.
I know folks often call these branches short lived feature branches but I think that completely misses the point. A feature is often cleaved up into pieces that span many short lived branches, a toggle prevents an incomplete feature being exposed before it's done
|
|
||
| - Rapid feedback loops and quicker issue resolution | ||
| - Reduced risk of large, complex merges | ||
| - Encourages small, frequent commits |
There was a problem hiding this comment.
Going directly via commits without branches also means review is really challenging!
|
|
||
| When implementing trunk-based development with Unleash, it's crucial to have a well-structured process for managing your feature flags and the associated code. This ensures the trunk remains in a deployable state while allowing teams to work independently on different features. | ||
|
|
||
| #### Establish Consistent Naming Conventions |
There was a problem hiding this comment.
Worth linking to our docs on flag naming patterns?
|
|
||
| - The feature or functionality the flag is associated with | ||
| - The environment or user segment the flag is intended for (e.g., "prod", "beta", "mobile\*users") | ||
| - A version or iteration number, if applicable |
There was a problem hiding this comment.
I'm not sure I completely understand what the version number is for?
|
|
||
| Regardless of the specific strategy, Unleash feature flag management capabilities are designed to support a wide range of trunk-based development styles, empowering you to implement the best strategy for your teams. | ||
|
|
||
| ### Microservices vs. Monoliths |
There was a problem hiding this comment.
This is bit of a hairy topic. I think all the points you've listed here can be challenged because they depend on a lot of things, like how well the code itself is structured and how source control is done. Are you mentioning this for completeness?
Not against this, just not sure where we're going with the thought
|
|
||
| #### Leverage Tagging and Metadata | ||
|
|
||
| In addition to meaningful names, apply relevant tags and metadata to your feature flags in Unleash. This metadata can include information such as: |
There was a problem hiding this comment.
Metadata? Like in the description of the flag?
| - Per-customer release | ||
| - General release | ||
|
|
||
| To target users accordingly, let's create an [activation strategy](/reference/activation-strategies). This Unleash concept defines who will be exposed to a particular flag. Unleash comes pre-configured with multiple activation strategies that let you enable a feature only for a specified audience, depending on the parameters under which you would like to release a feature. |
There was a problem hiding this comment.
Small detail here but a flag that's on in Unleash always has an activation strategy. If you haven't changed that in anyway it's set to 100% rollout, so you'll need to delete or just edit that strategy
|
|
||
| Unleash provides a powerful mechanism for safely managing and controlling these features in production, enabling enterprises to deliver software faster and with greater reliability. Effective feature flag management ensures that trunk-based development supports continuous delivery without compromising stability. In this tutorial, we’ll leverage Unleash to manage trunk-based development in your codebase. | ||
|
|
||
| ## How to Implement Trunk-Based Development with Feature Flags |
There was a problem hiding this comment.
Could we do sentence case for these please? 🙏 🙈
|
|
||
| Developers are increasingly adopting trunk-based development to accelerate software delivery and improve efficiency and reliability. A key principle of trunk-based development is merging code into the main branch (aka "trunk") as quickly as possible. This practice reduces the complexity of long-lived feature branches, minimizes merge conflicts, and ensures that teams can continuously integrate and test their code. However, it also means unfinished or experimental features may exist in production. This is where feature flags become essential. | ||
|
|
||
| Unleash provides a powerful mechanism for safely managing and controlling these features in production, enabling enterprises to deliver software faster and with greater reliability. Effective feature flag management ensures that trunk-based development supports continuous delivery without compromising stability. In this tutorial, we’ll leverage Unleash to manage trunk-based development in your codebase. |
There was a problem hiding this comment.
| Unleash provides a powerful mechanism for safely managing and controlling these features in production, enabling enterprises to deliver software faster and with greater reliability. Effective feature flag management ensures that trunk-based development supports continuous delivery without compromising stability. In this tutorial, we’ll leverage Unleash to manage trunk-based development in your codebase. | |
| Unleash provides a powerful mechanism for safely managing and controlling these features in production, enabling enterprises to deliver software faster and with greater reliability. Effective feature flag management ensures that trunk-based development supports continuous delivery without compromising stability. In this tutorial, we’ll use Unleash to manage trunk-based development in your codebase. |
|
|
||
| In this tutorial, you will: | ||
|
|
||
| 1. [Explore many trunk-based development strategies](#choose-the-right-trunk-based-development-strategy-for-your-team) |
There was a problem hiding this comment.
Since it's just two:
| 1. [Explore many trunk-based development strategies](#choose-the-right-trunk-based-development-strategy-for-your-team) | |
| 1. [Explore different trunk-based development strategies](#choose-the-right-trunk-based-development-strategy-for-your-team) |
|
|
||
| - Rapid feedback loops and quicker issue resolution | ||
| - Reduced risk of large, complex merges | ||
| - Encourages small, frequent commits |
There was a problem hiding this comment.
| - Encourages small, frequent commits | |
| - Small, frequent commits |
| **Advantages**: | ||
|
|
||
| - Improved control over the integration process | ||
| - Reduced risk of breaking the build with frequent merges |
There was a problem hiding this comment.
| - Reduced risk of breaking the build with frequent merges | |
| - Reduced risk of breaking the build |
|
|
||
| Imagine you've just rolled out a new checkout process. Shortly after launch, you detect performance issues or unexpected user behavior. To mitigate this issue, the process to roll back is straightforward: | ||
|
|
||
| 1. Navigate to the Unleash Admin UI |
There was a problem hiding this comment.
| 1. Navigate to the Unleash Admin UI | |
| 1. Go to the Unleash Admin UI |
|
|
||
| ## Archive and Remove Feature Flags | ||
|
|
||
| Once a feature is fully rolled out and stable, the feature flag should be archived or removed. This reduces clutter in the codebase and prevents unnecessary complexity. |
There was a problem hiding this comment.
| Once a feature is fully rolled out and stable, the feature flag should be archived or removed. This reduces clutter in the codebase and prevents unnecessary complexity. | |
| Once a feature is fully rolled out and stable, the feature flag should be archived or removed. This reduces technical debt in the codebase and prevents unnecessary complexity. |
|
|
||
| As your codebase and feature set grow over time, it's important to maintain visibility into your feature flag usage and lifecycle. Regularly review which flags are active, which environments they are enabled in, and when they were last modified. | ||
|
|
||
| Unleash provides reporting and analytics capabilities to help you monitor your feature flag landscape. This allows you to identify obsolete or unused flags, and plan for their eventual archival or removal, keeping your codebase clean and manageable. |
There was a problem hiding this comment.
Maybe link to feature flag life cycle here? https://docs.getunleash.io/reference/feature-toggles#feature-flag-lifecycle
| The trunk should always be deployable, enabling teams to accelerate release cycles and respond quickly to market demands. | ||
| To keep the trunk in a deployable state, keep the flag off in your production environment. The code for your feature should be wrapped in your flag and, therefore, not executable in production, even though the code will be deployed frequently. This ensures users will not have access to the feature before its official release. Additionally, this promotes collaboration by allowing teams to work independently on different features without interference. | ||
|
|
||
| To verify the functionality of your feature while it is incomplete, enable the flag in the development environment in the Unleash Admin UI. In some cases, you may also find it valuable to enable the flag in a testing/QA environment. Unleash environment-specific flag configurations make it easy to manage these different states across your [environments](/reference/environments#how-to-start-using-environments). You can quickly toggle flags on or off for specific environments, ensuring the trunk remains deployable in production while enabling active development and testing in other contexts. Use the default production environment toggle in Unleash to enable your flag when you’re ready to make your feature available. |
There was a problem hiding this comment.
| To verify the functionality of your feature while it is incomplete, enable the flag in the development environment in the Unleash Admin UI. In some cases, you may also find it valuable to enable the flag in a testing/QA environment. Unleash environment-specific flag configurations make it easy to manage these different states across your [environments](/reference/environments#how-to-start-using-environments). You can quickly toggle flags on or off for specific environments, ensuring the trunk remains deployable in production while enabling active development and testing in other contexts. Use the default production environment toggle in Unleash to enable your flag when you’re ready to make your feature available. | |
| To test your incomplete feature, enable the flag in the development environment in the Unleash Admin UI. In some cases, you may also find it valuable to enable the flag in a testing/QA environment. Unleash environment-specific flag configurations make it easy to manage these different states across your [environments](/reference/environments#how-to-start-using-environments). You can quickly toggle flags on or off for specific environments, ensuring the trunk remains deployable in production while enabling active development and testing in other contexts. Use the default production environment toggle in Unleash to enable your flag when you’re ready to make your feature available. |
There was a problem hiding this comment.
I think we could give a more realistic example here than the 'simple' tag, since we want to promote best practices.
About the changes
Trunk-based development preview
Gearing up to publish the Trunk-Based Development use case tutorial.
Closes #
Important files
Discussion points