Feature flag threshold ordering

[Prithpal-Sooriya]

Explanation

• What is the current state of things and why does it need to change?
  The RemoteFeatureFlagController evaluates threshold-scoped variations based on their order in the array. If these variations are not sorted in ascending order by their scope.value, the controller may select an unintended variation. This behavior was not explicitly documented or covered by a dedicated unit test, leading to potential confusion or misconfiguration.

• What is the solution your changes offer and how does it work?
  This PR clarifies and documents the expected behavior for threshold-scoped variations.

  1. A new unit test has been added to remote-feature-flag-controller.test.ts that explicitly demonstrates the controller selecting the first matching variation when the variations array is unsorted (e.g., [1, 0.1]). This test serves as a clear specification of the current implementation.
  2. The README.md for the remote-feature-flag-controller package has been updated with a new section, "Threshold-scoped variation ordering," which explicitly states that variations must be sorted in ascending order by their scope.value and provides correct/incorrect JSON examples.

• Are there any changes whose purpose might not obvious to those unfamiliar with the domain?
  The new unit test, which uses an unsorted array [1, 0.1] and asserts that the variation for 1 is selected, is crucial for documenting that the controller processes variations in array order, not necessarily by their numerical value if unsorted. This highlights the importance of the ascending order requirement now stated in the documentation.

References

#8122

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

---

  

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}