Update the CONTRIBUTING.md for our new roundtrip serializable world.

Author: nedtwigg

CONTRIBUTING.md

@@ -95,10 +95,31 @@ Here's a checklist for creating a new step for Spotless:
 
 - [ ] Class name ends in Step, `SomeNewStep`.
 - [ ] Class has a public static method named `create` that returns a `FormatterStep`.
-- [ ] Has a test class named `SomeNewStepTest`.
+- [ ] Has a test class named `SomeNewStepTest` that uses `StepHarness` or `StepHarnessWithFile` to test the step.
+  - [ ] Start with `StepHarness.forStep(myStep).supportsRoundTrip(false)`, and then add round trip support as decribed in the next section. 
 - [ ] Test class has test methods to verify behavior.
 - [ ] Test class has a test method `equality()` which tests equality using `StepEqualityTester` (see existing methods for examples).
 
+### Serialization roundtrip
+
+In order to support Gradle's configuration cache, all `FormatterStep` must be round-trip serializable. This is a bit tricky because step equality is based on the serialied form of the state, and `transient` is used to take absolute paths out of the equality check. To make this work, roundtrip compatible steps actually have *two* states
+
+- `RoundtripState` which must be roundtrip serializable but has no equality constraints
+  - `FileSignature.Promised` for settings files and `JarState.Promised` for the classpath 
+- `EqualityState` which will never be reserialized and its serialized form is used for equality / hashCode checks
+  - `FileSignature` for settings files and `JarState` for the classpath
+
+```java
+FormatterStep create(String name,
+  RoundtripState roundTrip,
+  SerializedFunction<RoundtripState, EqualityState> equalityFunc,
+  SerializedFunction<EqualityState, FormatterFunc> formatterFunc)
+FormatterStep createLazy(String name,
+  Supplier<RoundtripState> roundTrip,
+  SerializedFunction<RoundtripState, EqualityState> equalityFunc,
+  SerializedFunction<EqualityState, FormatterFunc> formatterFunc)
+```
+
 ### Third-party dependencies via reflection or compile-only source sets
 
 Most formatters are going to use some kind of third-party jar. Spotless integrates with many formatters, some of which have incompatible transitive dependencies. To address this, we resolve third-party dependencies using [`JarState`](https://github.com/diffplug/spotless/blob/b26f0972b185995d7c6a7aefa726c146d24d9a82/lib/src/main/java/com/diffplug/spotless/kotlin/KtfmtStep.java#L118). To call methods on the classes in that `JarState`, you can either use reflection or a compile-only source set. See [#524](https://github.com/diffplug/spotless/issues/524) for examples of both approaches.