Fragile Behavior — What Not to Break
Global SDK singleton
OpenFeatureAPI.getInstance() is process-wide state shared by all OpenFeature code in the JVM. This project funnels all provider registration through auto-config (setProviderAndWait). Registering a provider outside that path (in user code, tests, or a new module) can silently override what the Client bean serves.
Auto-configuration ordering
Provider auto-configs are @AutoConfigureBefore({ClientAutoConfiguration, MultiProviderAutoConfiguration}), and ClientAutoConfiguration is guarded by @ConditionalOnBean(FeatureProvider.class) + @ConditionalOnMissingBean(name = "multiProvider"). If a new provider forgets the @AutoConfigureBefore, the client may be built before the provider bean exists — and since @ConditionalOnBean is order-sensitive, the failure mode is a missing Client bean, not an error message.
The multiProvider bean name
ClientAutoConfiguration's @ConditionalOnMissingBean(name = "multiProvider") couples the generic and features/multi-provider modules by bean name. Renaming the MultiProvider bean method breaks that hand-off silently.
ToggleOnFlagAspect details
- A
System.out.printlndebug line runs for every SpEL attribute resolution (ToggleOnFlagAspect.resolveAttributesSpEL) — noisy and non-standard; treat as a known wart. - The
orElsefallback is invoked reflectively (Method.invokewith the original parameter types); a fallback with a different signature fails at runtime, not compile time. - SpEL expressions are evaluated with
StandardEvaluationContext(full SpEL, not the restricted variant) — anattributesexpression can reference anything in scope.
Failure semantics
Flag evaluation defaults to false everywhere. A down provider means all flag-gated code takes the off/fallback path — by design, but worth knowing when debugging "why did this feature just turn off?".
Design documents drift
docs/ replaced the OpenSpec trees on 2026-11-14. A design change that lands only in code silently re-creates the problem that killed the specs: the retired trees claimed mandatory properties that do not exist (Octopus Deploy, FeatBit) and stayed wrong because nothing enforced them. Update the matching docs/ page together with the decision — see overview/design-docs.
make lint must name the checkstyle execution
make lint and make checkstyle have to invoke checkstyle:check@checkstyle-validation.
The plugin's configLocation (the Spring ruleset), includeTestSourceDirectory=false and
violationIgnore=SpringNullability live on that one execution (pom.xml:276-288), so a bare
checkstyle:check inherits none of them and silently falls back to Checkstyle's default
sun_checks.xml — which reports 68 violations the project never enforced, including
80-character lines and FileTabCharacter (the repo indents Java with tabs on purpose).
Two ways this goes wrong quietly:
- Drop the
@checkstyle-validationsuffix and lint checks the wrong ruleset: red on clean code, and blind to the Spring rules that actually matter. - Give the target no recipe and the local
make-lintpre-commit hook reports "Passed" having run nothing — which is exactly how it shipped until 2026-11-14, alongside a duplicatedcheckstyle:target that mademakewarn on every call.
Verify either change behaviorally rather than by exit code: add a file with a java.util.*
star import and confirm the goal fails with AvoidStarImport.