PR#1: Update to asciidoctor-1.5.8 and other packaging cleanups - rpms/rubygem-asciidoctor

		`@@ -1,6 +1,5 @@`
		`- /asciidoctor-1.5.2.gem`
		`- /asciidoctor-1.5.3.gem`
		`- /asciidoctor-1.5.4.gem`
		`- /asciidoctor-1.5.5.gem`
		`- /asciidoctor-1.5.5-tests.tgz`
		`- /asciidoctor-1.5.6.1.gem`
		`+ /*.gem`
		`+ /*.rpm`
		`+ /.build*.log`
		`+ /asciidoctor-*/`
		`+ /results_*/`

README.adoc

file removed

-220

		`@@ -1,220 +0,0 @@`
		`- = rubygem-asciidoctor: Asciidoctor RPM package spec`
		`- Dan Allen`
		`- :idprefix:`
		`- :idseparator: -`
		`- :compat-mode!:`
		`- :gem_title: Asciidoctor`
		`- :gem_name: asciidoctor`
		`- :gem_version: 1.5.2`
		`- :gem_gem: {gem_name}-{gem_version}.gem`
		`- :gem_url: https://github.com/asciidoctor/asciidoctor`
		`- :rpm_name: rubygem-{gem_name}`
		`- :rpm_rpm: {rpm_name}-{gem_version}.rpm`
		`- :rpm_repo: git://github.com/asciidoctor/rubygem-asciidoctor-rpm.git`
		`-`
		`- This repository is the official host of the build materials to create the Fedora RPM package for the https://github.com/asciidoctor/asciidoctor[Asciidoctor] Ruby Gem.`
		- The RPM package is named `rubygem-asciidoctor`.
		`-`
		`- While this RPM spec was developed specifically for Fedora 18 and above, it may be useful for other RPM-based systems.`
		`-`
		`- == Build the Asciidoctor RPM`
		`-`
		`- If you want to build the RPM on your own machine, follow the instructions in this section.`
		`- If you want to test a pre-built package, skip to the next section on <<test-the-asciidoctor-rpm-and-report-feedback,testing the RPM>>.`
		`-`
		`- === Preparing your environment`
		`-`
		`- You first need to install the packages necessary to build the RPM.`
		- Begin by installing the `@fedora-packager` group (as root or using sudo):
		`-`
		`- yum install -y @fedora-packager wget`
		`-`
		`- Next, clone this repository and switch to it:`
		`-`
		`- git clone git://github.com/asciidoctor/rubygem-asciidoctor-rpm.git`
		`- cd rubygem-asciidoctor-rpm`
		`-`
		`- Finally, install the packages that this build requires (as root or using sudo):`
		`-`
		`- yum-builddep rubygem-asciidoctor.spec`
		`-`
		`- Next, we need to put the package source and patches in place.`
		`-`
		`- === Preparing the sources`
		`-`
		`- You can build RPMs as a non-privileged user, though you need to prepare the directories first.`
		- Let's use the directory rpmbuild in our `$HOME` directory:
		`-`
		`- echo "%_topdir %(echo $HOME)/rpmbuild" > $HOME/.rpmmacros`
		`-`
		`- You'll also need to create all the required folders:`
		`-`
		`- mkdir -p $HOME/rpmbuild/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}`
		`-`
		- Next, grab the Asciidoctor gem (the sources) and put it into the `$HOME/rpmbuild/SOURCES` directory:
		`-`
		`- wget -O $HOME/rpmbuild/SOURCES/asciidoctor-1.5.2.gem http://rubygems.org/gems/asciidoctor-1.5.2.gem`
		`-`
		- Finally, copy the `.patch` files from this repository to the same directory:
		`-`
		`- cp *.patch $HOME/rpmbuild/SOURCES/`
		`-`
		`- You're now ready to build the RPM.`
		`-`
		`- === Building the RPM`
		`-`
		`- With everything in place, building the RPM is easy!`
		`-`
		`- rpmbuild -ba rubygem-asciidoctor.spec`
		`-`
		- If all goes well, both the binary and source RPMs will emerge in the `$HOME/rpmbuild/RPMS/noarch` and `$HOME/rpmbuild/SRPMS` directories, respectively.
		`-`
		`- Alternatively, you can build directly from the SRPM.`
		`-`
		`- wget -P srpms http://kojipkgs.fedoraproject.org/packages/rubygem-asciidoctor/1.5.2/1.fc21/src/rubygem-asciidoctor-1.5.2-1.fc21.src.rpm`
		`- rpmbuild --rebuild srpms/rubygem-asciidoctor-1.5.2-1.fc21.src.rpm`
		`-`
		`- The SPRMs are stored with the builds in the http://koji.fedoraproject.org/koji/packageinfo?packageID=15660[koji build system].`
		`-`
		`- === Installing the RPM`
		`-`
		`- There's nothing special about installing this RPM.`
		- I recommend using `yum` because it will install any dependencies that the package requires (though you should already have them if you built the RPM).
		`-`
		`- yum install -y $HOME/rpmbuild/RPMS/noarch/rubygem-asciidoctor-1.5.2.rpm`
		`-`
		`- Now, it's time to start using Asciidoctor!`
		`-`
		`- == Test the Asciidoctor RPM and report feedback`
		`-`
		- Before the Asciidoctor package (`rubygem-asciidoctor`) can be included in the Fedora distribution, it must be tested by users and receive karma via the http://admin.fedoraproject.org/updates[Bohdi system].
		`- One way to provide this feedback is to use the http://admin.fedoraproject.org/pkgdb/acls/name/fedora-easy-karma[fedora-easy-karma] tool.`
		`-`
		`- === Enable the updates-testing repository temporarily`
		`-`
		`- In a terminal, type:`
		`-`
		`- yum install -y rubygem-asciidoctor --enablerepo=updates-testing`
		`-`
		`- This command will download and install the asciidoctor package.`
		`-`
		`- === Test the Asciidoctor API`
		`-`
		`- First, let's test using Asciidoctor as a Ruby library.`
		`-`
		- . On your computer, create a new file and name it `asciidoctor-test.rb`
		`- . Copy and paste the following code into the file:`
		`- +`
		`- [source,ruby]`
		`- ----`
		`- require 'asciidoctor'`
		`- content = "= My First Document\n\nRender me some HTML!"`
		`- puts Asciidoctor.render content, :header_footer => true`
		`- ----`
		`-`
		`- . Save the file.`
		- . In a terminal, navigate to the directory where you saved `asciidoctor-test.rb` and type the following command to execute the file with Ruby:
		`-`
		`- ruby asciidoctor-test.rb`
		`- +`
		`- You should see this output in your terminal.`
		`- +`
		`- [source,html]`
		`- ----`
		`- <!DOCTYPE html>`
		`- <html lang="en">`
		`- <head>`
		`- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">`
		`- <meta name="generator" content="Asciidoctor 1.5.2">`
		`- <meta name="viewport" content="width=device-width, initial-scale=1.0">`
		`- <title>My First Document</title>`
		`- <link rel="stylesheet" href="./asciidoctor.css">`
		`- </head>`
		`- <body class="article">`
		`- <div id="header">`
		`- <h1>My First Document</h1>`
		`- </div>`
		`- <div id="content">`
		`- <div id="preamble">`
		`- <div class="sectionbody">`
		`- <div class="paragraph">`
		`- <p>Render me some <strong>HTML</strong>!</p>`
		`- </div>`
		`- </div>`
		`- </div>`
		`- </div>`
		`- <div id="footer">`
		`- <div id="footer-text">`
		`- Last updated 2013-09-22 17:35:41 MDT`
		`- </div>`
		`- </div>`
		`- </body>`
		`- </html>`
		`- ----`
		`-`
		`- . You can render the output as HTML using:`
		`-`
		`- ruby asciidoctor-test.rb > asciidoctor-test.html`
		`-`
		`- . Open your browser to see the result.`
		`- . Alternatively, if you're using Gnome, type:`
		`-`
		`- gnome-open asciidoctor-test.html`
		`- +`
		`- A new tab should open in your current browser session.`
		`-`
		`- === Test the Asciidoctor CLI`
		`-`
		`- Now let's test using the Asciidoctor executable (i.e., CLI).`
		`-`
		`- . On your computer, create a new file and name it [path]_test.adoc_`
		`- . Copy and paste the following markup into the file:`
		`- +`
		`- ----`
		`- = My Second Document`
		`- Your Name`
		`-`
		`- AsciiDoc is _rockin'_ docs.`
		`- ----`
		`-`
		`- . Save the file`
		`- . In a terminal, navigate to the directory where you saved [path]_test.adoc_ and type the following command to run it through the Asciidoctor processor:`
		`-`
		`- asciidoctor test.adoc`
		`- +`
		`- You shouldn't see any output in your terminal.`
		- That's because it writes the output to the file `test.html`.
		`-`
		`- . Open your browser to see the result.`
		`- . Alternatively, if you're using Gnome, type:`
		`-`
		`- gnome-open test.html`
		`- +`
		`- A new tab should open in your current browser session.`
		`-`
		`- === Provide feedback with fedora-easy-karma`
		`-`
		`- . If you don't have fedora-easy-karma installed on your computer, type the following command in a terminal.`
		`-`
		`- yum install -y fedora-easy-karma`
		`-`
		`- . Once fedora-easy-karma is installed, run it in the terminal.`
		`-`
		`- fedora-easy-karma --fas-username <yourFASaccount> *asciidoctor`
		`- +`
		`- --`
		`- To be on the safe side, include the flag for your FAS account when you start fedora-easy-karma.`
		`- Once fedora-easy-karma runs, you will not be able to switch accounts.`
		`-`
		`- NOTE: It may take fedora-easy-karma several minutes to fetch the list of packages in updates-testing.`
		`-`
		- When fedora-easy-karma finds `rubygem-asciidoctor`, it will display a summary of the package and prompt you to give -1 (negative), 0 (neutral), or 1 (postive) karma to the package.
		`- For more information about providing karma for packages and how to comment on packages, review the http://fedoraproject.org/wiki/QA:Update_feedback_guidelines[Fedora feedback guidelines].`
		`- --`
		`-`
		`- . Enter your karma rating.`
		`- . Next, you will be asked to provide additional, detailed feedback.`
		`- Please comment whether the package worked as expected and you successfully used it, if you think you may have encountered an error, but aren't sure, or if you definitely encountered a bug.`
		`- . When prompted, enter your FAS password.`
		`- . W00t! The feedback process is complete.`
		`- . You can verify your feedback was recorded by visiting the https://admin.fedoraproject.org/updates[Bodhi updates page].`

rubygem-asciidoctor.rpmlintrc

file added

		`@@ -0,0 +1,7 @@`
		`+ from Config import *`
		`+`
		`+ # the dictionary is a bit limited`
		`+ addFilter("rubygem-asciidoctor\..*: W: spelling-error %description -l en_US toolchain")`
		`+`
		`+ # the asciidoctor-safe command is removed upstream for the next major release`
		`+ addFilter("rubygem-asciidoctor\..*: W: no-manual-page-for-binary asciidoctor-safe")`

rubygem-asciidoctor.spec

file modified

+10 -10

		`@@ -5,15 +5,11 @@`

		`Summary: A fast, open source AsciiDoc implementation in Ruby`
		`Name: rubygem-%{gem_name}`
		`- Version: 1.5.6.1`
		`- Release: 6%{?dist}`
		`+ Version: 1.5.8`
		`+ Release: 1%{?dist}`
		`License: MIT`
		`URL: https://github.com/asciidoctor/asciidoctor`
		`Source0: https://rubygems.org/gems/%{gem_name}-%{version}%{pre}.gem`
		`- # Parts of the test suite are missing from the package by accident.`
		`- # https://github.com/asciidoctor/asciidoctor/pull/1952`
		`- # git clone https://github.com/asciidoctor/asciidoctor.git && cd asciidoctor`
		`- # git checkout v1.5.5 && tar czvf asciidoctor-1.5.5-tests.tgz test/fixtures test/test_helper.rb`
		`%if 0%{?el7}`
		`Requires: ruby(release)`
		`BuildRequires: ruby(release)`
		`@@ -29,13 +25,13 @@`
		`# Dependencies aren't available on EPEL`
		`%else`
		`BuildRequires: rubygem(coderay)`
		`+ BuildRequires: rubygem(concurrent-ruby)`
		`BuildRequires: rubygem(erubis)`
		`BuildRequires: rubygem(haml)`
		`BuildRequires: rubygem(minitest)`
		`BuildRequires: rubygem(nokogiri)`
		`BuildRequires: rubygem(slim)`
		`BuildRequires: rubygem(tilt)`
		`- BuildRequires: rubygem(thread_safe)`
		`%endif`
		`BuildArch: noarch`
		`Provides: asciidoctor = %{version}`
		`@@ -85,10 +81,10 @@`
		`# Asciidoctor tests require Minitest 5, so we can't run them on EPEL`
		`%else`
		`sed -i "/test 'should convert asciimath macro content to MathML when asciimath gem is available' do/a \\`
		`- skip('asciimath gem is not avaiable on Fedora')" test/substitutions_test.rb`
		`+ skip('asciimath gem is not available on Fedora')" test/substitutions_test.rb`

		`sed -i "/should render asciimath block in textobject of equation in DocBook backend/a \\`
		`- skip('asciimath gem is not avaiable on Fedora')" test/blocks_test.rb`
		`+ skip('asciimath gem is not available on Fedora')" test/blocks_test.rb`

		`LANG=C.UTF-8 ruby -I"lib:test" -e 'Dir.glob "./test/*/_test.rb", &method(:require)'`
		`%endif`
		`@@ -117,10 +113,11 @@`
		`%exclude %{gem_instdir}/features`
		`%exclude %{gem_instdir}/Gemfile`
		`%exclude %{gem_instdir}/Rakefile`
		`- %license %{gem_instdir}/LICENSE.adoc`
		`+ %license %{gem_instdir}/LICENSE`
		`%doc %{gem_instdir}/CHANGELOG.adoc`
		`%doc %{gem_instdir}/CONTRIBUTING.adoc`
		`%doc %{gem_instdir}/README.*`
		`+ %lang(de) %doc %{gem_instdir}/README-de.*`
		`%lang(fr) %doc %{gem_instdir}/README-fr.*`
		`%lang(ja) %doc %{gem_instdir}/README-jp.*`
		`%lang(zh_CN) %doc %{gem_instdir}/README-zh_CN.*`
		`@@ -135,6 +132,9 @@`
		`%doc %{gem_docdir}`

		`%changelog`
		`+ * Tue Mar 19 2019 Todd Zullinger <tmz@pobox.com> - 1.5.8-1`
		`+ - Update to Asciidoctor 1.5.8 (resolves CVE-2018-18385)`
		`+`
		`* Sat Feb 02 2019 Fedora Release Engineering <releng@fedoraproject.org> - 1.5.6.1-6`
		`- Rebuilt for https://fedoraproject.org/wiki/Fedora_30_Mass_Rebuild`

sources

file modified

+1 -1

		`@@ -1,1 +1,1 @@`
		`- SHA512 (asciidoctor-1.5.6.1.gem) = cb23ab539b16b064e4a21575420abdaab34e20b7650a43b47df68ded1a424d1ab265c88102d4f3d3422bd30952fd93db7de254d61fdc253d17ffd93f1345bcdf`
		`+ SHA512 (asciidoctor-1.5.8.gem) = 34ff0df98ff9ebb2d3640629870cd848cf2f4b617564a42e7b30b6cf60c01d1188b4cc695af49550e054c9e833accc1ed5d622b4952ece3da99c8ed98af769ac`

tmz commented 5 years ago

Hi,

I noticed that our asciidoctor packages have not updated since 1.5.6.1 which was released in July 2017. The current stable release is 1.5.8 and contains a fix for a denial of service issue (CVE-2018-18385). While I was updating, I made a few other minor changes which I hope will be seen as improvements. The commit messages should explain them in detail. If not, let me know and I'll gladly expand on them.

My hope is that this update might prove suitable for stable releases after a bit of testing in rawhide. Upstream, the git project has been making strides toward allowing the documentation to build with asciidoctor. Git currently defaults to asciidoc, which is not as actively maintained upstream. For Fedora to benefit from that work, we'll want to have asciidoctor relatively up to date.

Thanks!

ktdreyer commented 5 years ago

The changes look good to me. I've given you commit access to the project, too.

Pull-Request has been merged by ktdreyer

5 years ago

tmz commented 5 years ago

Thanks @ktdreyer! I'll try to look at other packages which use asciidoctor and see if any incompatible changes turn up. If not, we can see about merging these changes to the stable fedora and epel7 branches (eventually, there's no reason to rush that part).

mojavelinux commented 5 years ago

Thanks for updating the package, @tmz! I really appreciate it. If there's anything you need from me, don't hesitate to let me know.

And just a heads up, 2.0.0 is about to drop upstream.

mojavelinux commented 5 years ago

It's really a shame that Pagure doesn't support the AsciiDoc format and that the README has to be removed, especially since Fedora uses AsciiDoc for documentation. Do you know if support for AsciiDoc is on the table? We could of course use Asciidoctor to implement it.

tmz commented 5 years ago

Thank you @mojavelinux. Good luck with the final 2.0.0 release polishing!

Being more familiar with the changes between 1.5.6.1 and 1.5.8, are there any changes which might make pushing 1.5.8 to the stable fedora releases problematic? (Essentially, anything that might run afoul of the updates policy.)

I saw that from 2.0.0, semantic versioning will be followed, which should make this question easier to answer in the future. :)

In case you're curious (or if you see some obvious ways we could resolve our minor asciidoc/asciidoctor man/html doc output differences), the recent thread on the git list is here.

tmz commented 5 years ago

It's really a shame that Pagure doesn't support the AsciiDoc format and that the README has to be removed, especially since Fedora uses AsciiDoc for documentation. Do you know if support for AsciiDoc is on the table? We could of course use Asciidoctor to implement it.

Yeah, I didn't want to remove it either. I considered migrating it to markdown which is supported, but that didn't seem like a worthy effort. (To say nothing of the sideways glances it might get to use markdown to format an asciidoctor README. ;)

The pagure README file handling is in pagure.doc_utils.convert_readme. It just falls back to wrapping the output in pre tags (though somewhere else the output loses all line breaks, so it was worse than just displaying the README.adoc as-is).

I did look at it yesterday before removing the file, to see if there was just a bug or an easy way to improve pagure's handling. Of course, I was already several layers deep in tangents so I didn't keep going and try to submit a pagure PR to better display README.adoc files without losing the line breaks and such.

I don't know if the pagure devs would accept a fork to run an external asciidoctor call or not. It may be worth filing a pagure issue to find out. The markdown support uses the python markdown module.

mojavelinux commented 5 years ago

Being more familiar with the changes between 1.5.6.1 and 1.5.8, are there any changes which might make pushing 1.5.8 to the stable fedora releases problematic?

Prior to 2.0, all patch numbers were major releases. And there were breaking changes in each. (See https://github.com/asciidoctor/asciidoctor/blob/master/CHANGELOG.adoc).

Once 2.0.0 is released, as you pointed out, we'll be following semantic versioning in the normal way.

tmz commented 5 years ago

Thanks for the clarification @mojavelinux. I looked at what packages BuildRequire asciidoctor and found the following: hugo mod_auth_mellon nanomsg ndctl nng qpid-dispatch wiki2beamer wsjtx.

Of those, qpid-dispatch is currently FTBFS (due to the cmake rules causing an empty file which is then fed to asciidoc -- yes, that package requires both asciidoc and asciidoctor for building different docs). I didn't feel like digging too much deeper on that because I think it's the cmake rules which are broken.

The others all build and the documentation changes look to be generally good, as in changes fix issues rather than cause them. One exception is in nanomsg. That package uses internal cross references which render properly with 1.5.6.1 and don't with 1.5.8.

Since 2.0.0 was released today, I'll retest with it and see if the problem still exists before reporting it further.

A PR to update to 2.0.0 will be coming in a moment, see you there. :)

mojavelinux commented 5 years ago

Thanks for doing this assessment.