From a22a639ec4bea18b3e912db69c9b322a78f87e9b Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Tue, 7 Jan 2020 00:05:51 -0500 Subject: [PATCH 1/2] doc: Explained the Opal problem in more depth and compatibility instructions --- HACKING.adoc | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/HACKING.adoc b/HACKING.adoc index 80f24260..f8f75252 100644 --- a/HACKING.adoc +++ b/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 with the `asciidoctor.js` release you are interested in: https://github.com/asciidoctor/asciidoctor.js/releases/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 version range to install by default for a given release (and on master) +* In the 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 <>. . Update dependencies and test the package in both languages + bundle update From 96845f16023b6b2bbb9fc8396e23da0200cbd5d7 Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Tue, 7 Jan 2020 00:11:37 -0500 Subject: [PATCH 2/2] doc: achieve npm package compatibility now and in the future (#187) Looks like this could work to address the Opal dependency problem. --- HACKING.adoc | 4 ++-- README.adoc | 27 ++++++++++++++++++++++++++- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/HACKING.adoc b/HACKING.adoc index f8f75252..cb5ab86e 100644 --- a/HACKING.adoc +++ b/HACKING.adoc @@ -267,8 +267,8 @@ Asciidoctor.js maintainer told us that he is going to consider binary package in We will track and maintain the README on the major version supported and recommended: -* In the version range to install by default for a given release (and on master) -* In the compatibility matrix +* 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. diff --git a/README.adoc b/README.adoc index 54f2b6af..f2a7e934 100644 --- a/README.adoc +++ b/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