Asciidoctor upgraded to 1.5.6.1

[dduportal]

This Pull Request aims to provide an upgrade of asciidoctor to the version 1.5.6.1.

This is the implementation for the issue #43.

It introduces the following changes:

• Installing Asciidoctor with gem instead of using the Alpine package, since the lifecycles are different
• Upgrading to the latest Asciidoctor v1.5.6.1 (instead of 1.5.5)

You can test with the prebuilt image from Docker Hub:

docker pull dduportal/docker-asciidoctor:adoc-gem-and-156

[mojavelinux]

I don't mind the change to gem install. Others may feel differently. I really wish it didn't take so long for a distribution package to sync with an upstream release. The 1.5.6.1 package has been in edge since the summer, but who knows when it will carry over to the stable alpine release.

[dduportal]

Thanks @mojavelinux for the fast feedback here!

I'm merging now since the overhead of moving to gem install is only of ~80 Mb uncompressed.

We can move back to native package as soon as we want!

[jirutka]

I really wish it didn't take so long for a distribution package to sync with an upstream release.

If you’re not happy with our latency in updating asciidoctor package, you can always send a pull request bumping abuild main/asciidoctor right after you release a new version.

However, when I look at numbers, you’ve released 1.5.6.1 at 0:04 GMT on July 24 and I’ve bumped asciidoctor package at 16:39 GMT the same day (i.e. ~16 hours)…

The 1.5.6.1 package has been in edge since the summer, but who knows when it will carry over to the stable alpine release.

Everyone (can) know, it’s documented on wiki here – we release a new stable version each 6 months. The current stable branch is v3.6 (the latest version 3.6.2), the next one will be v3.7 (in few weeks).

All changes goes right to the branch “edge” (aka unstable), this is basically rolling. You can install complete system or just selected packages from “edge”, but it’s not recommended for production (especially mixing stable and edge), there may be breakages. Each stable branch starts as a snapshot of the edge, usually 1–4 weeks before vX.Y.0 is released. We have only short freeze period and two stable branches per year. So what is currently in edge will be in the next stable release.

Only bug fixes and security fixes are backported into stable branches (otherwise it’d not be really stable). Support period and type of support is documented here. This is quite standard among linux distributions.

When you compare Alpine with other distributions, we have quite short release cycles and it takes quite short time to upstream releases get into stable. I understand that it’s still slow from PoV of upstream project, but as you know, it’s always a compromise between many conflicting requirements.

However, it’s very easy for anyone (with some experience with linux) to create, modify or backport Alpine package to whatever version s(he) wants. I do it regularly for my needs (jirutka/user-aports). And that’s also what I did at the beginning for needs of docker-asciidoctor after I created packages for some dependencies (before v3.6 was released).

[jirutka]

I'm merging now since the overhead of moving to gem install is only of ~80 Mb uncompressed.

That actually quite a lot! How’s that possible? asciidoctor gem has just few hundreds of kiB, not MiB!

[dduportal]

Hello @jirutka, I think this might be related to base dependencies.

I am not a Ruby user, so I did not have time nor knowledge to dig in. The trade-off between having a ~200 Mb image instead of ~120 Mb seems good enough compared to the need of having the last asciidoctor version.

The change can still be reverted with in the future, but it has to be discussed with @mojavelinux (and any other person willing to help here) if we want to build something like your backport system.
The main concern I have with this is the time to spend on this topic. Maybe it is easy and quick for you as an Alpine Linux contributor, but it might not be the same for any other Asciidoctor contributor.

=> The goal here is to tie the Docker Image lifecycle to the asciidoctor release's one. If a backport solution with Alpine Linux Package helps on this, why not. But what would be the "implications" (having to server packages from a server? How to maintain access, etc?"?

Thanks for your help and your tips!

[jirutka]

I think this might be related to base dependencies.

But asciidoctor gem doesn’t have any dependencies except Ruby… Where can I see some build log? Travis is empty.

The goal here is to tie the Docker Image lifecycle to the asciidoctor release's one.

I understand that and it makes sense. That’s why I suggested to install it from Rubygems instead of Aports, it gives you more flexibility in this sense. I just don’t recommend this approach for gems with native extensions, but that’s not case of the asciidoctor gem.

[mojavelinux]

you’ve released 1.5.6.1 at 0:04 GMT on July 24 and I’ve bumped asciidoctor package at 16:39 GMT the same day (i.e. ~16 hours)…

I appreciate your timeliness on upgrading the package. That is not where my compliant lies.

Where I disagree is that a gem upgrade only makes it to the stable version of the distribution when a new distribution is released. That seems like a strange coupling to me.

Having said that, I understand fully that Asciidoctor doesn't currently follow semantic versioning, so the releases could be perceived (and arguably are) major releases. And for that reason, I can understand the conservative approach.

But regardless of philosophies, it's clear that the community wants direct control over the version of the gem that this Docker container uses and for that, the best approach for that is gem install.

[mojavelinux]

I just don’t recommend this approach for gems with native extensions, but that’s not case of the asciidoctor gem.

👍

[mojavelinux]

I am not a Ruby user, so I did not have time nor knowledge to dig in. The trade-off between having a ~200 Mb image instead of ~120 Mb seems good enough compared to the need of having the last asciidoctor version.

I don't think this is really about a tradeoff. Something happened that caused the image to increase by 80MB and it couldn't possibly be caused by gem install. We are using gem install for a whole bunch of other gems, so the only increase you should see is the size of the Asciidoctor gem, which is ~ 2 MB extracted.

[mojavelinux]

My guess is that the increase in size came when you put the jre back in for asciidoctor-diagram. So the image increased in size, just not because of how it installed asciidoctor.

[dduportal]

Hello @jirutka , thanks for the help and explanations!
As far as I know, build logs are currently on the DockerHub: https://hub.docker.com/r/asciidoctor/docker-asciidoctor/builds/

I have opened the issue #50 for keeping track of this "image size" concern, and #49 for the CD process.

[dduportal]

@mojavelinux you are totally right: I measured very badly the diff.

I checked it today, comparing the DockerHub latest image, a local build of the master branch (the gem tag) and a native installation (alpine-pkg tag with asciidoctor 1.5.5) :

docker image ls | grep docker-asciidoctor
docker-asciidoctor               alpine-pkg          4bb12eedc2b3        21 minutes ago      438MB
docker-asciidoctor               gem                 2b838fa2c1b3        26 minutes ago      438MB
asciidoctor/docker-asciidoctor   latest              e77547cb35c1        25 hours ago        438MB

Images are the same size.

I am sorry for the confusion.

[mojavelinux]

👍