Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Address the Opal and Asciidoctor.js compatibility #303

Merged
merged 2 commits into from
Jan 7, 2020
Merged

Address the Opal and Asciidoctor.js compatibility #303

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a22a639
doc: Explained the Opal problem in more depth and compatibility instr…
obilodeau Jan 7, 2020
96845f1
doc: achieve npm package compatibility now and in the future (#187)
obilodeau Jan 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions HACKING.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
27 changes: 26 additions & 1 deletion README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down