How we handle feature retirement and what you can expect when features are deprecated
Deprecation is the process of marking a feature as no longer recommended for use, typically because a better alternative exists or the feature no longer aligns with the platform direction.
A feature is marked as deprecated when it is scheduled for retirement. The feature continues to work during the deprecation period, but users are encouraged to transition to alternatives.
Removal is when a feature is no longer available. This typically follows a deprecation period. Once removed, the feature cannot be accessed, and workflows depending on it will need adjustment.
Key Distinction: Deprecation is an announcement and transition period. Removal is the final action. We aim to provide sufficient time between the two for users to adapt.
Features may be deprecated for various reasons. Understanding these scenarios helps you anticipate and plan for potential changes.
Features in experimental status may be discontinued if they do not meet adoption or quality thresholds for progression.
Features that remain in beta without progressing to production may eventually be deprecated if they are superseded or no longer align with platform goals.
Even stable production features may be deprecated when significantly improved alternatives become available. This is the least common scenario and is handled with the most care.
In rare cases, features may need to be deprecated due to security concerns, regulatory requirements, or foundational technical changes.
When a feature is deprecated, it typically moves through the following stages. The duration and specifics vary based on feature maturity and impact.
The feature is marked as deprecated. Release notes explain the deprecation, the reason, and any recommended alternatives. The feature continues to function normally.
Users can continue using the feature while planning their transition. Documentation is updated with deprecation notices and guidance on alternatives.
The feature is removed from the platform or replaced with its successor. Users who have not transitioned will need to update their workflows.
Note: The duration of each stage depends on the feature's maturity level and user impact. Production features receive longer deprecation periods than experimental features.
We use multiple channels to communicate deprecation decisions, ensuring users have visibility into upcoming changes.
All deprecation decisions are documented in our What's New page. Deprecated features are clearly labeled with context on timing and alternatives.
Documentation for deprecated features is updated with clear notices, including links to recommended alternatives. The Feature Status page reflects current deprecation status.
Where applicable, deprecated features may display notices within the application to inform users who are actively using them. These notices link to documentation and alternatives.
The Version History page tracks deprecation events as part of each feature's lifecycle, providing a complete record of changes over time.
While we work to minimize disruption from deprecation, users share responsibility for managing transitions effectively.
We encourage you to review release notes periodically to stay informed of deprecation announcements. This gives you the maximum time to plan any necessary transitions.
When a feature you use is deprecated, begin planning your transition early. Evaluate alternatives, update your workflows, and validate that replacements meet your needs.
After transitioning to alternative features, validate that your workflows produce the expected results. Final responsibility for output accuracy remains with you.
Features with lower maturity levels (experimental, beta) carry higher deprecation risk. Factor this into your decisions when building workflows around less mature features.
A feature's maturity level directly affects its deprecation risk and the notice you can expect. Understanding this relationship helps you assess risk when adopting features.
This feature is stable and production-ready. Results can be relied upon for business decisions.
This feature is functional and improving. Review results before final decisions.
This feature is exploratory. Use for investigation only, not for final decisions.
For critical workflows, we recommend relying primarily on production-maturity features. These offer the strongest stability guarantees and longest deprecation notice periods. Use beta and experimental features for exploration and non-critical use cases.
See Also: Backward Compatibility Policy for details on how compatibility expectations vary by maturity level.