Add Fluent PR gate to prevent Settings API backwards-compatibility regressions
- Dominant language
- Python
- Stars
- 497
- Forks
- 77
- Avg merge
- 22h 37m
- Merged PRs (30d)
- 45
Description
## Summary
We’re seeing frequent backwards-compatibility breaks in the Fluent Settings API that surface in PyFluent as unexpected breakages (examples, docs, downstream code). This creates significant triage + maintenance load for the PyFluent team and ultimately impacts end users by breaking compatibility expectations.
## Problem
When Settings API items are removed or otherwise made unavailable unexpectedly between Fluent versions, it introduces compatibility regressions that are difficult to detect early and costly to correct after the fact.
## Request
Introduce a centralized Fluent-side test that detects backwards-compatibility violations at the Settings API level.
### What the test should do
* Maintain a baseline snapshot derived from the **last released Fluent version’s** static Settings API info.
* Compare the current PR’s generated static info against that baseline.
* **Fail / block** the PR if any Settings API items are removed (or otherwise become unavailable) in a way that violates the compatibility policy.
* Run as part of Fluent’s **central PR pre-commit / CI checks**, so regressions are caught before merge.
### Compatibility rules for removals
Not all removals are necessarily violations.
**Standard removal rule**
There is already a deprecation attribute on deprecated items indicating the Fluent version in which the item was deprecated, and this attribute is included in the static info.
An API item may be removed **only** once it has been deprecated for at least the universally defined support period (i.e. removal occurs after the allowed deprecation window).
**Exceptional removals**
In exceptional circumstances, API items may be removed outside the standard deprecation policy, but **only with explicit approval** from the API architecture / management team. Such items must not be removed without these approvals.
Exceptional circumstances include, but are not limited to:
- API sections requiring such a radical redesign that replacement is necessary.
- API sections that were added without intent to be released (noting that the current framework does not reliably distinguish between experimental/under-development sections and released API).
In all such cases, management reserves the right to approve or refuse any requested removal.
## Outcome / benefit
This will:
* Prevent accidental compatibility breaks before they reach PyFluent.
* Reduce triage and reactive fixes across examples/docs.
* Improve end-user experience by upholding compatibility promises.
Contributor guide
Research direction
Start by locating Fluent’s generated static Settings API information and the central PR pre-commit or CI checks where a compatibility test could run. Done means comparing the current PR against the last released baseline, allowing only removals permitted by the deprecation window or explicit approval, and blocking other regressions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, ci-cd, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100