Publish a migration guide to complement the Asciidoctor 2 upgrade
Antora 3 will include a upgrade from Asciidoctor.js 1.5.9 (Asciidoctor 1.5.8) to Asciidoctor.js 2.2 (Asciidoctor 2). When users upgrade to Antora 3, they will automatically be upgraded to Asciidoctor 2 as well. There are noteworthy changes between Asciidoctor 1.5.8 and Asciidoctor 2 that could impact existing sites. To help users prepare for this migration, and to make it a smooth one, the docs should include a migration guide. This guide should inform users what changes to expect, communicate what actions need to be taken to minimize the impact of those changes, and notify users what new features / capabilities are available.
To start off, the guide should communicate that the version of Asciidoctor.js and Asciidoctor are different. To an Antora user, the version of Asciidoctor.js isn't significant. It's really the Asciidoctor version that Asciidoctor.js uses that matters. That version will be Asciidoctor 2.0.15.
Also note that, starting with Asciidoctor 2, Asciidoctor has switched to semantic versioning. This will allow Antora to use newer patch version of Asciidoctor.js without making a new release.