HACKING.adoc in asciidoctor-revealjs-3.0.0.pre.rc1 vs HACKING.adoc in asciidoctor-revealjs-3.0.0

- old
+ new

@@ -205,16 +205,18 @@ Remember that this is a slower moving project since people are not designing slides everyday. Well, for most people. === Work-in-progress pull-requests -If you prepend "WIP" in front of your pull request we will understand that it is not complete and we will not merge it before you remove the WIP string. +Letting know to the maintainers that you are working on a feature or a fix is useful. +Early communication often times save time consuming mistakes or avoids duplicated effort. +We encourage contributors to communicate with us early. -This is useful to let people know that you are working on stuff. -Branches are not that visible otherwise but pull requests are. +Branches on forks of this project are not very visible to maintainers as much as pull requests (PR). +For this reason we used to recommend sending a PR even if it's not ready and prepend "WIP" in front of its name to let everyone see that you are working on a specific topic. +Now, instead of prepending "WIP", we recommend using GitHub "draft pull request" feature instead. -You might even be able to get some feedback early which could save you some time. === 'needs review' label You can apply that label to a pull request that is complete and ready for review. @@ -242,18 +244,39 @@ NOTE: The relative portion of the last command is where you are installing the local `asciidoctor-reveal.js` version from. Then proceed as documented in the `README.adoc`. -=== Upgrade Asciidoctor.js version +[[node-binary-compatibility]] +=== Binary package compatibility with Asciidoctor.js -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. -The former is specified in our `package.json` and the latter in the `asciidoctor-revealjs.gemspec`. -When you update one remember to update the other. +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: + 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 [[ruby-localversion]] === Test a local asciidoctor-revealjs version @@ -271,25 +294,49 @@ $ bundle --path=.bundle/gems --binstubs=.bundle/.bin == 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 + bundle exec rake build + bundle exec rake doctest + bundle exec rake examples:convert + npm update --no-save + bundle exec rake build:js + npm test + npm run examples + +. Commit the updated dependencies . Update the version in `lib/asciidoctor-revealjs/version.rb` and `package.json` . Update the changelog ** Generate author list with: + git log <prev-version-tag>.. --format="%aN" --reverse | perl -e 'my %dedupe; while (<STDIN>) { print unless $dedupe{$_}++}' | sort . Prepare release commit +** Add the "Slim compiled to Ruby" converter to the git tree (otherwise ignored to avoid noise to the repo) ++ + bundle exec rake build + git add -f lib/asciidoctor-revealjs/converter.rb + ** commit msg: Prepare %version% release ** release commit (--allow-empty) msg: Release %version% . Tag the release commit ** Annotated Tag msg: Version %version% . Push your changes (including the tag) . Make a release on github (from changelog and copy from previous releases) -// TODO: reg needs fixin' -** Useful vim regex for AsciiDoc to Markdown: `:%s/{uri-issue}\d\+\(\(\[#\d\+\)]\)/\1(https:\/\/github.com\/asciidoctor\/asciidoctor-reveal.js\/issues\/\2)/gc` +** Useful vim regex for AsciiDoc to Markdown: ++ + :%s/{uri-issue}\(\d\+\)\[#\d\+]/#\1/gc + :%s/{project-name}/asciidoctor-reveal.js/gc + :%s/\(.*\)::/### \1/gc + . Pushing the gem on rubygems.org: + $ bundle exec rake build $ gem build asciidoctor-revealjs.gemspec $ gem push asciidoctor-revealjs-X.Y.Z.gem @@ -297,19 +344,15 @@ . Check that the new version is available on https://rubygems.org/gems/asciidoctor-revealjs[rubygems.org] . Generate the javascript version of the Ruby converter + $ bundle exec rake build:js -. Test the node package (make sure you have `devDependencies` installed with: `npm install`): -+ - $ npm run test - . Publish the node package on npm: + $ npm login # only required if not already authenticated $ npm publish -. Check that the new version is available on https://www.npmjs.com/package/asciidoctor-reveal.js[npmjs.com] +. Check that the new version is available on https://www.npmjs.com/package/@asciidoctor/reveal.js[npmjs.com] . Update version in `lib/asciidoctor-revealjs/version.rb` and `package.json` (+1 bugfix and append '-dev') and commit ** commit msg: Begin development on next release . Submit a PR upstream to sync the documentation on asciidoctor.org ** Modify this page: https://github.com/asciidoctor/asciidoctor.org/edit/master/docs/asciidoctor-revealjs.adoc