From e7e9410ddd7d30ea216f15e6cc6fd9fa16b4992f Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 1 Jan 2020 16:05:51 -0500 Subject: [PATCH 1/6] doc: Instructions to add generated converter on releases (fixes #265) --- .gitignore | 2 +- HACKING.adoc | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index f7bc8430..c8b83a0e 100644 --- a/.gitignore +++ b/.gitignore @@ -17,5 +17,5 @@ build/ /.bundle/ /Gemfile.lock -# the compiled slim template +# the compiled slim template, committed only on releases to avoid noise /lib/asciidoctor-revealjs/converter.rb diff --git a/HACKING.adoc b/HACKING.adoc index 5e9da6c5..3e865245 100644 --- a/HACKING.adoc +++ b/HACKING.adoc @@ -280,6 +280,11 @@ Then run: git log .. --format="%aN" --reverse | perl -e 'my %dedupe; while () { 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 From 604f31d4e6a180e1c8ef3a3f10bdba482e80a566 Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 1 Jan 2020 16:08:59 -0500 Subject: [PATCH 2/6] doc: updated how to sync Opal versions This has been wrong since b9b52d5dd7 where we started building an Opal ready converter with Rake (Ruby) instead of npm.No need to sync the package.json anymore. --- HACKING.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/HACKING.adoc b/HACKING.adoc index 3e865245..281df129 100644 --- a/HACKING.adoc +++ b/HACKING.adoc @@ -248,9 +248,9 @@ Then proceed as documented in the `README.adoc`. 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. 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`. + == RubyGem package From cd6294043b2968906d16b52a1046a7ef36117116 Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 1 Jan 2020 16:19:09 -0500 Subject: [PATCH 3/6] doc: More vim regexes help to convert CHANGELOG to release notes --- HACKING.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/HACKING.adoc b/HACKING.adoc index 281df129..4e6a830d 100644 --- a/HACKING.adoc +++ b/HACKING.adoc @@ -291,7 +291,12 @@ Then run: ** Annotated Tag msg: Version %version% . Push your changes (including the tag) . Make a release on github (from changelog and copy from previous releases) -** 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 From 28ab4fc5c66380ad1eaaf39fb832bdf31bdaa0b3 Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 1 Jan 2020 16:30:40 -0500 Subject: [PATCH 4/6] doc: Updated WIP to include GitHub's draft pull request feature --- HACKING.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/HACKING.adoc b/HACKING.adoc index 4e6a830d..8587bfb1 100644 --- a/HACKING.adoc +++ b/HACKING.adoc @@ -207,12 +207,14 @@ 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 From 54af19f37ad449f28dac85cf54c9b342387004b8 Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 1 Jan 2020 16:46:15 -0500 Subject: [PATCH 5/6] doc: testing javascript environment earlier in the release process Also more thoroughly described --- HACKING.adoc | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/HACKING.adoc b/HACKING.adoc index 8587bfb1..2c7b4fd0 100644 --- a/HACKING.adoc +++ b/HACKING.adoc @@ -275,6 +275,19 @@ Then run: == Release process + +. 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: @@ -310,10 +323,6 @@ Then run: + $ 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 From 2792309882d1e6a86db24dc96de104bb21fa5f6e Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 1 Jan 2020 16:50:31 -0500 Subject: [PATCH 6/6] doc: updated release process for new npm package name --- HACKING.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HACKING.adoc b/HACKING.adoc index 2c7b4fd0..80f24260 100644 --- a/HACKING.adoc +++ b/HACKING.adoc @@ -328,7 +328,7 @@ Then run: $ 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