Skip to content

Simplify deprecation policy #4259

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.

Sign up for GitHub

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

Open
wied03 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Simplify deprecation policy #4259

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 2 additions & 19 deletions astro/src/content/docs/operate/roadmap/deprecation-policy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Deprecation Policy
description: Learn more about the FusionAuth deprecation policy.
---

FusionAuth is an architectural component integrated into your applications or systems. Such integration means that when changes to FusionAuth occur, it can negatively affect your application. As developers ourselves, we strive to maintain backwards compatibility.
FusionAuth is an architectural component integrated into your applications or systems. Such integration means that when changes to FusionAuth occur, it can negatively affect your application. As developers ourselves, we strive to maintain backwards compatibility. We will not remove API support in minor or patch versions (only in major versions), except for security/performance reasons noted below.
Copy link
Copy Markdown
Contributor

@nathan-contino nathan-contino Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Considering we have only ever released one major version, should this instead say:

Suggested change
FusionAuth is an architectural component integrated into your applications or systems. Such integration means that when changes to FusionAuth occur, it can negatively affect your application. As developers ourselves, we strive to maintain backwards compatibility. We will not remove API support in minor or patch versions (only in major versions), except for security/performance reasons noted below.
FusionAuth is an architectural component integrated into your applications or systems. Such integration means that when changes to FusionAuth occur, it can negatively affect your application. As developers ourselves, we strive to maintain backwards compatibility. Only minor and major versions will change API support (never patch releases).

suggestion: I always find it easier to understand conditionals like this when we avoid negatives
suggestion: if we extend this to 'major and minor', maybe we can omit the consideration about security and performance reasons?
nitpick: avoid slashes, preferring 'and' and 'or' when possible


However, there are times when features or functionality must be removed. FusionAuth has [extensive release notes](/docs/release-notes/), which are the source of truth for changes to the FusionAuth system, and any deprecated features will be listed there. Changes to existing features or behavior will also be documented in the release notes.

Expand Down Expand Up @@ -34,24 +34,7 @@ The releases mentioned in this document are either major or point version releas
Before removing a feature, the FusionAuth team takes the following steps:

* In the first major or point release where the behavior is deprecated, the deprecation is noted in the release notes. The feature is also marked as deprecated in the documentation.
* The feature deprecation is noted in the documentation for three months.
* In a major or point release after the three month deprecation period, the feature and corresponding documentation are removed. When the feature is removed, it is noted in the release notes. The documentation for the feature is also removed.

While the team commits to maintaining features for at least three months after they are deprecated, that timeframe is a minimum.

## Example Removal Timeline

Suppose the current release is 1.52.0 and FusionAuth planned to remove feature ABC in the next release. Here is what the timeline would look like.

| FusionAuth Version | Date Released | Feature ABC Changes | Release Notes Updates |
| -------- | ------- | ------- | ------- |
| 1.52.0 | March 1, 2024 | None | None |
| 1.52.1 | March 8, 2024 | None | None |
| 1.53.0 | April 1, 2024 | Feature documentation marked as deprecated. | Deprecation announced in release notes. |
| 1.53.1 | April 5, 2024 | Feature documentation remains marked as deprecated. | None |
| 1.53.2 | April 15, 2024 | Feature documentation remains marked as deprecated. | None |
| 1.54.0 | May 15, 2024 | Feature documentation remains marked as deprecated. | None |
| 1.55.0 | July 13, 2024 | Feature and documentation removed. | Feature removal announced in release notes. |
* In a major release after the behavior is deprecated, the feature and corresponding documentation are removed. When the feature is removed, it is noted in the release notes. The documentation for the feature is also removed.
Copy link
Copy Markdown
Contributor

@nathan-contino nathan-contino Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean 'one major release after' or is this a noncommittal 'some major release after'? It might be better to be explicit here.

Copy link
Copy Markdown
Contributor

@mooreds mooreds Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is confusing to me because we don't do major releases. We only do minor and patch releases.

Suggested change
* In a major release after the behavior is deprecated, the feature and corresponding documentation are removed. When the feature is removed, it is noted in the release notes. The documentation for the feature is also removed.
* In a minor release after the behavior is deprecated, the feature and corresponding documentation are removed. When the feature is removed, it is noted in the release notes. The documentation for the feature is also removed.

Copy link
Copy Markdown
Contributor

@mooreds mooreds Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd also prefer to keep the 3 month minimum timeframe, but I suppose that is an engineering decision.


## Policy Exceptions

Expand Down
Loading