rabbitmq/rabbitmq-website

rabbit_exchange_type_local_random feature flag is not documented

teodor-mysko opened this issue · 4 comments

teodor-mysko commented

Describe the bug

After upgrading from RabbitMQ 3.13.7 to RabbitMQ 4.0.2 We see that rabbit_exchange_type_local_random flag is listed in a feature table, but that flag is not documented in https://www.rabbitmq.com/docs/feature-flags#core-feature-flags.

Additional question: why rabbit_exchange_type_local_random and rabbitmq_4.0.0 flags are disabled by default after an upgrade but at the same time they are enabled by default when installing from scratch the latest version?

Reproduction steps

  1. Install latest version of RabbitMQ Server (or upgrade from older one)
  2. Run rabbitmqctl -q --formatter pretty_table list_feature_flags name state provided_by desc doc_url command to see list of feature flags
  3. Search for rabbit_exchange_type_local_random flag and try to find it on a documentation page

...

Expected behavior

Documentation should have an information about rabbit_exchange_type_local_random flag

Additional context

No response

michaelklishin commented

FYI, the website is open source.

michaelklishin commented

@teodor-mysko rabbit_exchange_type_local_random is not documented because it is no longer used independently. It is a part of rabbitmq_4.0.0, which is documented.

Our team does not use issues for questions but since there's nothing to update: as explained in the Feature Flags guide, feature flags are a safety mechanism for upgrades. Both the Feature Flags one and the guide on Upgrades explain that you must enable all stable feature flags (plus any opt-in flags you intent to use) at the end of an upgrade. RabbitMQ cannot know when would be a good moment to do that and, as with many things on this team, we do not guess. When the user considers a cluster upgrade to be done, they enable the flags.

When a node starts as a blank one, it is obvious that this is not an upgrade scenario and there are no reasons not to enable all stable flags.

slarti-b commented

@michaelklishin : I still see this as a bug. If it's not a separate flag then the output of the list_feature_flags command should not list it. If it is listed there then it should be listed in the documentation. The documentation can say what you said above, but we should be able to look at the documentation to see what each of the flags in the output of the list_feature_flags command means. How are we, as users, supposed to know that some of flags listed by the program as feature flags aren't really feature flags anymore?

Or, at least, the docs should list under the entry for rabbitmq_4.0.0 all the flags that it takes over for

michaelklishin commented

@slarti-b should be listed in the documentation to what end? For the sake of being listed? The best description I have for it is "see this other doc guide".

Most feature flags are not at all interesting, they exist so that a certain piece of code can avoid doing something potentially unsafe when the cluster is in a mixed-version mode.

If it is a stable feature flag, enable it and move on. khepri_db is the only exception and it has not one but multiple doc guides.