Add doc for behavior change configuration

[MonkeyCanCode]

We are missing doc for https://github.com/apache/polaris/blob/main/polaris-core/src/main/java/org/apache/polaris/core/config/BehaviorChangeConfiguration.java.

Checklist

• 🛡️ Don't disclose security issues! (contact security@apache.org)
• 🔗 Clearly explained why the changes are needed, or linked related issues: Fixes #
• 🧪 Added/updated tests with good coverage, or manually tested (and explained how)
• 💡 Added comments for complex logic
• 🧾 Updated CHANGELOG.md (if needed)
• 📚 Updated documentation in site/content/in-dev/unreleased (if needed)

[adutra]

Hi @MonkeyCanCode I'm not sure the "behavior change" flags were meant to be exposed publicly. Their javadocs say:

Internal configuration flags for non-feature behavior changes in Polaris. These flags control subtle behavior adjustments and bug fixes, not user-facing settings. They are intended for internal use only, are inherently unstable, and may be removed at any time. When introducing a new flag, consider the trade-off between maintenance burden and the risk of an unguarded behavior change. Flags here are generally short-lived and should either be removed or promoted to stable feature flags before the next release.

Of course... those flags have been there for a long time now and were neither removed nor promoted to stable flags 😄

Therefore, I'm not sure we should expose them in documentation – at least not before assessing if they should be removed or promoted.

Wdyt?

[MonkeyCanCode]

Hi @MonkeyCanCode I'm not sure the "behavior change" flags were meant to be exposed publicly. Their javadocs say:

Internal configuration flags for non-feature behavior changes in Polaris. These flags control subtle behavior adjustments and bug fixes, not user-facing settings. They are intended for internal use only, are inherently unstable, and may be removed at any time. When introducing a new flag, consider the trade-off between maintenance burden and the risk of an unguarded behavior change. Flags here are generally short-lived and should either be removed or promoted to stable feature flags before the next release.

Of course... those flags have been there for a long time now and were neither removed nor promoted to stable flags 😄

Therefore, I'm not sure we should expose them in documentation – at least not before assessing if they should be removed or promoted.

Wdyt?

Got it. Yeah, I was working on something and had to use one of them then noticed none of these are documented. Will start a ML for it. Thanks for the quick review @adutra.

[adutra]

An ML discussion thread would be perfect, thanks!

[MonkeyCanCode]

those flags have been there for a long time now and were neither removed nor promoted to stable flags

Thanks for review @adutra . ML: https://lists.apache.org/thread/8fgszl9jw9718dstlh3dxn0o1g8wkrh4

[flyrain]

I'm OK to add them in the doc. Most of them are user-facing config indeed.

[MonkeyCanCode]

Merged as concluded on the ML. We will clean up risky ones in a diff PR.