Document the behavior of default branches present for version skew

PiperOrigin-RevId: 755065063

Author: kevinoconnor7

docs/bugpattern/MissingCasesInEnumSwitch.md

@@ -29,3 +29,41 @@ switch statement on an enum type to either handle all values of the enum, or
 have a default statement group.
 
 [style]: https://google.github.io/styleguide/javaguide.html#s4.8.4.3-switch-default
+
+## Library skew
+
+If libraries are compiled against different versions of the same enum it's
+possible for the switch statement to encounter an enum value despite it
+otherwise being thought to be exhaustive. If there is no default branch code
+execution will simply fall out of the switch statement.
+
+Since developers may have assumed this to be impossible, it may be helpful to
+add a default branch when library skew is a concern, however, you may not want
+to give up checking to ensure that all cases are handled. Therefore if a default
+branch exists with a comment containing "skew", the default will not be
+considered for exhaustiveness. For example:
+
+```java
+enum TrafficLightColour { RED, GREEN, YELLOW }
+
+void approachIntersection(TrafficLightColour state) {
+  switch (state) {
+    case GREEN:
+      proceed();
+      break;
+    case YELLOW:
+    case RED:
+      stop();
+      break;
+    default: // In case of skew we may get an unknown value, always stop.
+      stop();
+      break;
+  }
+}
+```
+
+In this case the default branch is providing runtime safety for unknown enum
+values while also still enforcing that all known enum values are handled.
+
+Note: The [UnnecessaryDefaultInEnumSwitch](UnnecessaryDefaultInEnumSwitch.md)
+check will not classify the default as unnecessary if it has the "skew" comment.

docs/bugpattern/UnnecessaryDefaultInEnumSwitch.md

@@ -153,3 +153,8 @@ If it can complete normally, the default should be merged with an added
 UNRECOGNIZED case.
 
 [complete normally]: https://docs.oracle.com/javase/specs/jls/se10/html/jls-14.html#jls-14.1
+
+## Library skew
+
+A default branch that has a comment containing "skew" will not be classified as
+unnecessary. See: [MissingCasesInEnumSwitch](MissingCasesInEnumSwitch.md).