Skip to content

Commit 5fd2176

Browse files
dumbbelldumbbell
committed
deprecated-features: Document the Deprecated features subsystem
The list of deprecated features is also documented in the release information section.
1 parent e239257 commit 5fd2176

File tree

8 files changed

+380
-0
lines changed

8 files changed

+380
-0
lines changed

‎docs/deprecated-features/index.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Deprecated Features
3+
---
4+
<!--
5+
Copyright (c) 2024 Broadcom. All Rights Reserved. The term "Broadcom" refers
6+
to Broadcom Inc. and/or its subsidiaries.
7+
8+
All rights reserved. This program and the accompanying materials
9+
are made available under the terms of the under the Apache License,
10+
Version 2.0 (the "License”); you may not use this file except in compliance
11+
with the License. You may obtain a copy of the License at
12+
13+
https://www.apache.org/licenses/LICENSE-2.0
14+
15+
Unless required by applicable law or agreed to in writing, software
16+
distributed under the License is distributed on an "AS IS" BASIS,
17+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
See the License for the specific language governing permissions and
19+
limitations under the License.
20+
-->
21+
22+
# Deprecated Features
23+
24+
## Overview
25+
26+
Over time, some features of RabbitMQ are not relevant anymore. Sometimes, a
27+
feature must go away to leave the room for a better replacement. Before we
28+
deorbit a feature, we follow a deprecation time window: we announce that a
29+
feature is deprecated along with the reasoning, how user should prepare for
30+
that and the estimated future version of RabbitMQ where this deprecated
31+
feature will be removed and unsupported.
32+
33+
Beside the public announcement, RabbitMQ has a Deprecated features subsystem
34+
that helps notify users right from the broker if they are using a feature that
35+
will be removed in the future.
36+
37+
You can view the [list of actually deprecated features in a dedicated
38+
page](/release-information/deprecated-features-list).
39+
40+
## The lifecycle of a deprecated feature
41+
42+
The Deprecated features subsystem is based on the [Feature flags
43+
subsystem](./feature-flags). Therefore, much like a feature flag which goes
44+
from experimental to stable to required, a deprecated feature follow the
45+
following phases:
46+
47+
1. **Permitted by default**. A user can continue to use the feature. They just
48+
get warnings in the logs and can use a configuration knob to start RabbitMQ
49+
as if the feature was removed for testing purpose.
50+
2. **Denied by default**. The feature is still there, but it is not usable out
51+
of the box, like if it was already removed. A user can turn it back on from
52+
the configuration.
53+
3. **Disconnected**. The feature is still present in the code, but it is
54+
compiled out in official packages. A user has to recompile RabbitMQ from
55+
source to be able to continue to use it. Note that we do not plan to use
56+
this phase very often, if ever.
57+
4. **Removed**. The code of the feature is gone and it is not possible to use
58+
it anymore. This is the equivalent of a required feature flag.
59+
60+
## Checking if deprecated features are used
61+
62+
In addition to the [full list of deprecated
63+
features](/release-information/deprecated-features-list) documented on this
64+
website, you can view the deprecated features for a specific RabbitMQ
65+
deployment using:
66+
* the [CLI](./man/rabbitmq-diagnostics.8)'s `rabbitmq-diagnostics list_deprecated_features`
67+
* the [management UI](./management) Admin > Deprecated Features panel
68+
69+
You can query RabbitMQ to find out if a node or cluster is actively using one
70+
or more deprecated features:
71+
72+
```sh
73+
rabbitmq-diagnostics check_if_any_deprecated_features_are_used
74+
```
75+
76+
It lists used deprecated features (if any) and exits with 0 if none are used,
77+
or non-zero if one or more deprecated features are actively used.
78+
79+
You can do the same using the HTTP API:
80+
81+
```
82+
GET /api/deprecated-features/used
83+
```
84+
85+
:::info
86+
Note that the result of these queries depends on if the use of a deprecated
87+
feature can be detected or not. For instance, it is possible to detect if
88+
classic queue mirroring is used. However it is not for global QoS.
89+
:::
90+
91+
## Configuring deprecated features behavior
92+
93+
As described above, a user may decide to turn off a deprecated feature to test
94+
the behavior of RabbitMQ and their applications as if the feature was already
95+
removed.
96+
97+
```ini
98+
# Try RabbitMQ as if the deprecated feature was gone.
99+
deprecated_features.permit.some_deprecated_feature = false
100+
```
101+
102+
Another user may decied to turn a *denied by default* deprecated feature back
103+
on to buy more time to adapt their applications while still upgrading
104+
RabbitMQ:
105+
106+
```ini
107+
# Permit a deprecated feature that is denied by default.
108+
deprecated_features.permit.some_deprecated_feature = true
109+
```

‎release-information/deprecated-features-list.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: List of Deprecated Features
3+
---
4+
<!--
5+
Copyright (c) 2024 Broadcom. All Rights Reserved. The term "Broadcom" refers
6+
to Broadcom Inc. and/or its subsidiaries.
7+
8+
All rights reserved. This program and the accompanying materials
9+
are made available under the terms of the under the Apache License,
10+
Version 2.0 (the "License”); you may not use this file except in compliance
11+
with the License. You may obtain a copy of the License at
12+
13+
https://www.apache.org/licenses/LICENSE-2.0
14+
15+
Unless required by applicable law or agreed to in writing, software
16+
distributed under the License is distributed on an "AS IS" BASIS,
17+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
See the License for the specific language governing permissions and
19+
limitations under the License.
20+
-->
21+
22+
# List of Deprecated Features
23+
24+
| Deprecated&nbsp;feature | Deprecated&nbsp;since | Removed&nbsp;in | Notes |
25+
|--------------------|---------------|------------|-------|
26+
| [`amqp_address_v1`](/docs/amqp#address-v1) | RabbitMQ 4.0 | | Use [AMQP address v2](/docs/amqp#address-v2). |
27+
| [`classic_queue_mirroring`](/docs/3.13/ha) | [August&nbsp;2021](/blog/2021/08/21/4.0-deprecation-announcements) | RabbitMQ&nbsp;4.0 | Use [quorum queues](/docs/quorum-queues). |
28+
| `global_qos` | [August&nbsp;2021](/blog/2021/08/21/4.0-deprecation-announcements) | | Use per-consumer QoS. |
29+
| `management_metrics_collection` | [August&nbsp;2021](/blog/2021/08/21/4.0-deprecation-announcements) | | Use the [Prometheus plugin](/docs/prometheus). |
30+
| `ram_node_type` | [August&nbsp;2021](/blog/2021/08/21/4.0-deprecation-announcements) | | Use disk nodes only. |
31+
| `transient_nonexcl_queues` | [August&nbsp;2021](/blog/2021/08/21/4.0-deprecation-announcements) | | Prefer a [queue TTL](/docs/ttl#queue-ttl) for auto-deleting unused queues. |
32+
33+
See the [Deprecated Features subsystem documentation](/docs/deprecated-features) to learn how deprecated features are managed.

‎sidebarsDocs.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,11 @@ const sidebars = {
127127
id: 'feature-flags/index',
128128
label: 'Feature Flags',
129129
},
130+
{
131+
type: 'doc',
132+
id: 'deprecated-features/index',
133+
label: 'Deprecated Features',
134+
},
130135
],
131136
},
132137
{

‎sidebarsReleaseInfo.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ const sidebars = {
1919
id: 'index',
2020
label: 'Release Information',
2121
},
22+
{
23+
type: 'doc',
24+
id: 'deprecated-features-list',
25+
label: 'Deprecated Features',
26+
},
2227
],
2328
};
2429

‎versioned_docs/version-3.13/deprecated-features/index.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Deprecated Features
3+
---
4+
<!--
5+
Copyright (c) 2024 Broadcom. All Rights Reserved. The term "Broadcom" refers
6+
to Broadcom Inc. and/or its subsidiaries.
7+
8+
All rights reserved. This program and the accompanying materials
9+
are made available under the terms of the under the Apache License,
10+
Version 2.0 (the "License”); you may not use this file except in compliance
11+
with the License. You may obtain a copy of the License at
12+
13+
https://www.apache.org/licenses/LICENSE-2.0
14+
15+
Unless required by applicable law or agreed to in writing, software
16+
distributed under the License is distributed on an "AS IS" BASIS,
17+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
See the License for the specific language governing permissions and
19+
limitations under the License.
20+
-->
21+
22+
# Deprecated Features
23+
24+
## Overview
25+
26+
Over time, some features of RabbitMQ are not relevant anymore. Sometimes, a
27+
feature must go away to leave the room for a better replacement. Before we
28+
deorbit a feature, we follow a deprecation time window: we announce that a
29+
feature is deprecated along with the reasoning, how user should prepare for
30+
that and the estimated future version of RabbitMQ where this deprecated
31+
feature will be removed and unsupported.
32+
33+
Beside the public announcement, RabbitMQ has a Deprecated features subsystem
34+
that helps notify users right from the broker if they are using a feature that
35+
will be removed in the future.
36+
37+
You can view the [list of actually deprecated features in a dedicated
38+
page](/release-information/deprecated-features-list).
39+
40+
## The lifecycle of a deprecated feature
41+
42+
The Deprecated features subsystem is based on the [Feature flags
43+
subsystem](./feature-flags). Therefore, much like a feature flag which goes
44+
from experimental to stable to required, a deprecated feature follow the
45+
following phases:
46+
47+
1. **Permitted by default**. A user can continue to use the feature. They just
48+
get warnings in the logs and can use a configuration knob to start RabbitMQ
49+
as if the feature was removed for testing purpose.
50+
2. **Denied by default**. The feature is still there, but it is not usable out
51+
of the box, like if it was already removed. A user can turn it back on from
52+
the configuration.
53+
3. **Disconnected**. The feature is still present in the code, but it is
54+
compiled out in official packages. A user has to recompile RabbitMQ from
55+
source to be able to continue to use it. Note that we do not plan to use
56+
this phase very often, if ever.
57+
4. **Removed**. The code of the feature is gone and it is not possible to use
58+
it anymore. This is the equivalent of a required feature flag.
59+
60+
## Checking if deprecated features are used
61+
62+
In addition to the [full list of deprecated
63+
features](/release-information/deprecated-features-list) documented on this
64+
website, you can view the deprecated features for a specific RabbitMQ
65+
deployment using:
66+
* the [CLI](./man/rabbitmq-diagnostics.8)'s `rabbitmq-diagnostics list_deprecated_features`
67+
* the [management UI](./management) Admin > Deprecated Features panel
68+
69+
You can query RabbitMQ to find out if a node or cluster is actively using one
70+
or more deprecated features:
71+
72+
```sh
73+
rabbitmq-diagnostics check_if_any_deprecated_features_are_used
74+
```
75+
76+
It lists used deprecated features (if any) and exits with 0 if none are used,
77+
or non-zero if one or more deprecated features are actively used.
78+
79+
You can do the same using the HTTP API:
80+
81+
```
82+
GET /api/deprecated-features/used
83+
```
84+
85+
:::info
86+
Note that the result of these queries depends on if the use of a deprecated
87+
feature can be detected or not. For instance, it is possible to detect if
88+
classic queue mirroring is used. However it is not for global QoS.
89+
:::
90+
91+
## Configuring deprecated features behavior
92+
93+
As described above, a user may decide to turn off a deprecated feature to test
94+
the behavior of RabbitMQ and their applications as if the feature was already
95+
removed.
96+
97+
```ini
98+
# Try RabbitMQ as if the deprecated feature was gone.
99+
deprecated_features.permit.some_deprecated_feature = false
100+
```
101+
102+
Another user may decied to turn a *denied by default* deprecated feature back
103+
on to buy more time to adapt their applications while still upgrading
104+
RabbitMQ:
105+
106+
```ini
107+
# Permit a deprecated feature that is denied by default.
108+
deprecated_features.permit.some_deprecated_feature = true
109+
```

‎versioned_docs/version-4.0/deprecated-features/index.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Deprecated Features
3+
---
4+
<!--
5+
Copyright (c) 2024 Broadcom. All Rights Reserved. The term "Broadcom" refers
6+
to Broadcom Inc. and/or its subsidiaries.
7+
8+
All rights reserved. This program and the accompanying materials
9+
are made available under the terms of the under the Apache License,
10+
Version 2.0 (the "License”); you may not use this file except in compliance
11+
with the License. You may obtain a copy of the License at
12+
13+
https://www.apache.org/licenses/LICENSE-2.0
14+
15+
Unless required by applicable law or agreed to in writing, software
16+
distributed under the License is distributed on an "AS IS" BASIS,
17+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
See the License for the specific language governing permissions and
19+
limitations under the License.
20+
-->
21+
22+
# Deprecated Features
23+
24+
## Overview
25+
26+
Over time, some features of RabbitMQ are not relevant anymore. Sometimes, a
27+
feature must go away to leave the room for a better replacement. Before we
28+
deorbit a feature, we follow a deprecation time window: we announce that a
29+
feature is deprecated along with the reasoning, how user should prepare for
30+
that and the estimated future version of RabbitMQ where this deprecated
31+
feature will be removed and unsupported.
32+
33+
Beside the public announcement, RabbitMQ has a Deprecated features subsystem
34+
that helps notify users right from the broker if they are using a feature that
35+
will be removed in the future.
36+
37+
You can view the [list of actually deprecated features in a dedicated
38+
page](/release-information/deprecated-features-list).
39+
40+
## The lifecycle of a deprecated feature
41+
42+
The Deprecated features subsystem is based on the [Feature flags
43+
subsystem](./feature-flags). Therefore, much like a feature flag which goes
44+
from experimental to stable to required, a deprecated feature follow the
45+
following phases:
46+
47+
1. **Permitted by default**. A user can continue to use the feature. They just
48+
get warnings in the logs and can use a configuration knob to start RabbitMQ
49+
as if the feature was removed for testing purpose.
50+
2. **Denied by default**. The feature is still there, but it is not usable out
51+
of the box, like if it was already removed. A user can turn it back on from
52+
the configuration.
53+
3. **Disconnected**. The feature is still present in the code, but it is
54+
compiled out in official packages. A user has to recompile RabbitMQ from
55+
source to be able to continue to use it. Note that we do not plan to use
56+
this phase very often, if ever.
57+
4. **Removed**. The code of the feature is gone and it is not possible to use
58+
it anymore. This is the equivalent of a required feature flag.
59+
60+
## Checking if deprecated features are used
61+
62+
In addition to the [full list of deprecated
63+
features](/release-information/deprecated-features-list) documented on this
64+
website, you can view the deprecated features for a specific RabbitMQ
65+
deployment using:
66+
* the [CLI](./man/rabbitmq-diagnostics.8)'s `rabbitmq-diagnostics list_deprecated_features`
67+
* the [management UI](./management) Admin > Deprecated Features panel
68+
69+
You can query RabbitMQ to find out if a node or cluster is actively using one
70+
or more deprecated features:
71+
72+
```sh
73+
rabbitmq-diagnostics check_if_any_deprecated_features_are_used
74+
```
75+
76+
It lists used deprecated features (if any) and exits with 0 if none are used,
77+
or non-zero if one or more deprecated features are actively used.
78+
79+
You can do the same using the HTTP API:
80+
81+
```
82+
GET /api/deprecated-features/used
83+
```
84+
85+
:::info
86+
Note that the result of these queries depends on if the use of a deprecated
87+
feature can be detected or not. For instance, it is possible to detect if
88+
classic queue mirroring is used. However it is not for global QoS.
89+
:::
90+
91+
## Configuring deprecated features behavior
92+
93+
As described above, a user may decide to turn off a deprecated feature to test
94+
the behavior of RabbitMQ and their applications as if the feature was already
95+
removed.
96+
97+
```ini
98+
# Try RabbitMQ as if the deprecated feature was gone.
99+
deprecated_features.permit.some_deprecated_feature = false
100+
```
101+
102+
Another user may decied to turn a *denied by default* deprecated feature back
103+
on to buy more time to adapt their applications while still upgrading
104+
RabbitMQ:
105+
106+
```ini
107+
# Permit a deprecated feature that is denied by default.
108+
deprecated_features.permit.some_deprecated_feature = true
109+
```

‎versioned_sidebars/version-3.13-sidebars.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,11 @@
103103
"id": "feature-flags/index",
104104
"label": "Feature Flags"
105105
},
106+
{
107+
"type": "doc",
108+
"id": "deprecated-features/index",
109+
"label": "Deprecated Features"
110+
},
106111
{
107112
"type": "doc",
108113
"id": "blue-green-upgrade",

0 commit comments

Comments
 (0)