Merge pull request #303 from obilodeau/doc-asciidoctor.js-stability

Address the Opal and Asciidoctor.js compatibility

HACKING.adoc

@@ -246,13 +246,34 @@ NOTE: The relative portion of the last command is where you are installing the l
 
 Then proceed as documented in the `README.adoc`.
 
-=== Upgrade Asciidoctor.js version
+[[node-binary-compatibility]]
+=== Binary package compatibility with Asciidoctor.js
+
+Asciidoctor.js is source-to-source compiled into JavaScript from Ruby using Opal.
+The JavaScript generated requires a specific version of the Opal-runtime for it to work with Node.js.
+This project is source-to-source compiled into JavaScript from Ruby using Opal too.
+In order for Asciidoctor.js to be able to call code from this converter, the versions of Opal (both runtime and compiler) must be compatible.
+Right now we track the exact git revision of Opal used by Asciidoctor.js and make sure that we match.
+Here is how:
 
-WARNING: It is important to track `Asciidoctor.js` and `opal` versions together.
-The `opal` used to compile our node package must match `asciidoctor.js`'s `opal` requirement.
 Versions known to work together can be found by looking at the Asciidoctor.js release notes, just replace <tag> with the `asciidoctor.js` release you are interested in: https://github.com/asciidoctor/asciidoctor.js/releases/tag/<tag>.
 Then that Opal version and git revision (if required) must be specified in `asciidoctor-revealjs.gemspec`.
 
+Starting with 3.0.0 we aim to retain binary compatibility between Asciidoctor.js and Asciidoctor-reveal.js.
+This should allow other Asciidoctor extensions to be called along with this converter.
+Asciidoctor.js is no longer a direct dependency but should be seen as a tool that powers this converter.
+We need to allow users to have flexibility in the version they choose to run.
+Asciidoctor.js maintainer told us that he is going to consider binary package incompatibility a major break and so we adjusted our README to tell users to install with a specific version range.
+
+We will track and maintain the README on the major version supported and recommended:
+
+* In the link:README.adoc#node-install[version range to install by default] for a given release (and on master)
+* In the link:README.adoc#asciidoctorjs-compatibility-matrix[compatibility matrix]
+
+See https://github.com/asciidoctor/asciidoctor-reveal.js/issues/187#issuecomment-570771473[this issue] for background details on that topic.
+
+Asciidoctor.js versioning policy is https://asciidoctor-docs.netlify.com/asciidoctor.js/project/version-and-lifecycle-policies/[available here].
+
 
 == RubyGem package
 
@@ -276,6 +297,8 @@ Then run:
 == Release process
 
 
+. Do we need to do anything regarding our Opal dependency and Asciidoctor.js?
+  See <<node-binary-compatibility,our section on the topic>>.
 . Update dependencies and test the package in both languages
 +
     bundle update

README.adoc

@@ -134,6 +134,7 @@ TIP: If you are using https://pages.github.com/[GitHub Pages], plan ahead by kee
 
 First you must install and configure {uri-nodejs-download}[Node] on your machine.
 
+[[node-install]]
 === Install
 
 We recommend to install the dependencies in a project directory, such as the directory where your AsciiDoc presentations are stored.
@@ -143,7 +144,7 @@ If you don't have a `package.json` file in your project directory, you can creat
 
 You can now install the dependencies:
 
- $ npm i --save asciidoctor @asciidoctor/reveal.js
+ $ npm i --save asciidoctor@^2.0 @asciidoctor/reveal.js
 
 === Convert AsciiDoc into slides
 
@@ -1004,6 +1005,30 @@ If you need more details about our dependencies check out Asciidoctor dependenci
 * With Ruby / Bundler: https://github.com/asciidoctor/asciidoctor/tree/v2.0.10#requirements[Asciidoctor] 2.0.10
 * With JavaScript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v2.0.3/packages/core/package.json[Asciidoctor.js] 2.0.3
 
+[[asciidoctorjs-compatibility-matrix]]
+== Asciidoctor.js Compatibility Matrix
+
+NOTE: This section is intended only for more advanced users who combine extensions or maintain slide decks over many releases and need to update their dependencies.
+
+Due to our Ruby to JavaScript conversion process, published npm packages have strict requirements with which version of Asciidoctor.js they are compatible with.
+This table tracks this compatibility.
+
+|===
+|Asciidoctor-reveal.js version |Asciidoctor.js version
+
+|3.x
+|2.x
+
+|2.x
+|1.5.9
+
+|1.1.x
+|1.5.6-preview.4
+|===
+
+Be aware that it is always possible to recompile the converter into JavaScript from source so compatibility can be created by anyone if needed.
+More details on that topic can be found link:HACKING.adoc#node-binary-compatibility[in the development guide].
+
 
 == Showcase Presentations