Document more about how and why to migrate off Truth8.

This continues our work on #746.

RELNOTES=n/a
PiperOrigin-RevId: 607454835

core/src/main/java/com/google/common/truth/Truth8.java

@@ -33,7 +33,11 @@
  * The obsolete entry point for assertions about Java 8 types.
  *
  * @deprecated Instead of this class's methods, use the identical methods declared in the main
- *     {@link Truth} class.
+ *     {@link Truth} class. In most cases, you can <a
+ *     href="https://github.com/google/truth/releases/tag/v1.4.0">migrate</a> your whole project
+ *     mechanically: {@code git grep -l Truth8 | xargs perl -pi -e 's/\bTruth8\b/Truth/g;'}
+ *     Migration is important <i>if</i> you static import {@code assertThat}: If you do not migrate,
+ *     such static imports will become ambiguous in Truth 1.4.2, breaking your build.
  */
 @Deprecated
 // The methods here are no more dangerous that wherever the user got the (e.g.) Stream.