1## Behavior changes
2
3### Changes that affect API documentation
4
5Do not make behavior changes that require altering API documentation in a way
6that would break existing clients, even if such changes are technically binary
7compatible. For example, changing the meaning of a method's return value to
8return true rather than false in a given state would be considered a breaking
9change. Because this change is binary-compatible, it will not be caught by
10tooling and is effectively invisible to clients.
11
12Instead, add new methods and deprecate the existing ones if necessary, noting
13behavior changes in the deprecation message.
14
15### High-risk behavior changes
16
17Behavior changes that conform to documented API contracts but are highly complex
18and difficult to comprehensively test are considered high-risk and should be
19implemented using behavior flags. These changes may be flagged on initially, but
20the original behaviors must be preserved until the library enters release
21candidate stage and the behavior changes have been appropriately verified by
22integration testing against public pre-release
23revisions.
24
25It may be necessary to soft-revert a high-risk behavior change with only 24-hour
26notice, which should be achievable by flipping the behavior flag to off.
27
28```java
29// Flag for whether to throw exceptions when the state is known to be bad. This
30// is expected to be a high-risk change since apps may be working fine even with
31// a bad state, so we may need to disable this as a hotfix.
32private static final boolean FLAG_EXCEPTION_ON_BAD_STATE = false;
33```
34
35```java
36/**
37 * Allows a developer to toggle throwing exceptions when the state is known to
38 * be bad. This method is intended to give developers time to update their code.
39 * It is temporary and will be removed in a future release.
40 */
41@TemporaryFeatureFlag
42public void setExceptionOnBadStateEnabled(boolean enabled);
43```
44
45Avoid adding multiple high-risk changes during a feature cycle, as verifying the
46interaction of multiple feature flags leads to unnecessary complexity and
47exposes clients to high risk even when a single change is flagged off. Instead,
48wait until one high-risk change has landed in RC before moving on to the next.
49
50#### Testing
51
52Relevant tests should be run for the behavior change in both the on and off
53flagged states to prevent regressions.
54