Create releases/tags for Docker Images

[mgreau]

As explained in the Docker development best practices documentation:

Do not rely on the automatically-created latest tag.

We need to create git tags and docker tags for each new version (as we do for others projects):

• the master branch will always be built as latest tag
• each time we create a release (tag on GitHub), then we need to create a tag on the DockerHub admin UI manually.

Tag/version

We need to decide how to tag this project.
IMO the most important thing is to be able to quickly know the asciidoctor versions included in the docker image.
We can either:

1. based the tag/version on the asciidoctor version (examples: 1.5.6.1-1.0.0 or 1.0.0-1.5.6.1)
2. manage only the docker-asciidoctor version in the tag (example:1.0.0) AND add LABEL in the Dockerfile to add metatada about the asciidoctor projects versions:

    LABEL org.asciidoctor.version="1.5.6.1" \
     org.asciidoctor-pdf.version="1.5.0.alpha.16" \
     org.asciidoctor-epub3.version="1.5.0.alpha.7"...
   

• then those information will be available via the docker inspect command

I vote for the solution 2) because it will be easy for the users to pull the right Docker Image version (docker pull asciidoctor/docker-asciidoctor:1.0.0) and to know the exact asciidoctor versions included.

Note: I'm ok to do the manual steps when we need to perform a release (we can think about automating it later)

[dduportal]

Hello @mgreau , thanks for putting this together!

I personally vote for a mix of 1 and 2:

1. (Having tags following the asciidoctor version + latest to the latest stable)

• A lot of users are still not aware of the docker inspect.
• Running docker inspect on the image requires it to be already downloaded, so the binary is already there. As soon as the user as the "expectation" to get the image, then it should be able to choose it without requiring to download it (or to consult a big matrix of versions on a web page :) )
• This image as an "asciidoctor" first, "rest of the ecosystem 2nd": having its lifecycle following along the asciidoctor releases would be a great value
• Maintenance and automation: we could have a release done (or at least prepared) each time a new release of asciidoctor is released in the gem store.

By the way, I still love your 2) proposal:

• Integrating the "other tools" version as metadata (using the LABEL instructions) make a lot of sense

Why not a mix of those?

[mgreau]

This image as an "asciidoctor" first, "rest of the ecosystem 2nd": having its lifecycle following along the asciidoctor releases would be a great value

Well, if we plan to separate the "rest of the ecosystem 2nd" and create a separate image with only asciidoctor, I would say ok :)
But in the actual case, let's say we have an asciidoctor/docker-asciidoctor:1.5.6.1 tag and the asciidoctor-pdf-1.5.0 is released.
Do we have to wait for an asciidoctor release to upgrade the asciidoctor-pdfversion in a Docker Image available on the DockerHub? (for me the latest tag doesn't exist because you can't plug a CI process based on this tag AND a tag is immutable)

But I agree that it's easy for users to have the same version for the asciidoctor version and the Docker image version.

Maintenance and automation: we could have a release done (or at least prepared) each time a new release of asciidoctor is released in the gem store.

+1 (even if we may have to do it manually in a first step)

[bmustiata]

As a side note, if you have an automated build, and the execution is triggered for the tags, you don't need to manually go and create the tags. The dockerhub will get notified through its hooks from github and the build and tag will be triggered automatically.

You just need to push your git tags, and dockerhub will pick them up and use them for the tag.

[dduportal]

Hello!

After running in the "not using fix tag" trouble, and reading @mgreau proposal #2 (special version for this + using Labels), looks like a very good thing!

@mgreau How do your prefer to operate: shall I update the pull request #61 or shall we do a subsequent PR ?

[mgreau]

@dduportal I think it might be better to do a subsequent PR so that other contributors can see both solutions.

[dduportal]

👍

[mojavelinux]

Given the direction the Asciidoctor community is about to take with regards to versions, I strongly recommend either aligning exactly with the Asciidoctor core version or introducing your own versioning scheme. Since the container provides more than just Asciidoctor core, I don't see a strong case for using the version number of core. You might just be better off following your own semantic versioning series.

[dduportal]

After recent bumping of asciidoctor to 2.x, and some issues when rebuilding (see #92 for example),
and considering #79 , what do you think about the following:

• docker run --rm asciidoctor/asciidoctor:2.0.6 --version => this image only contains asciidoctor as a CLI. Anyone can tune its own "toolbox" with a FROM asciidoctor/asciidoctor:2.0.6
  • lightweight
  • It should be built from the Git repository of original asciidoctor, to always be in sync
  • Can be used for ANY docker-based customization
• docker run --rm asciidoctor/asciidoctor-box:1.0.0 asciidoctor --version => this image is the "kitchen sink" (aka. asciidoctor + other tools
  • This is the actual asciidoctor/docker-asciidoctor image, but renamed to have an explicit meaning
  • It's based upon the asciidoctor/asciidoctor image, with a fixed version
  • Any other dependencies (as asciidoctor-pdf for example) have their versions written in the image's metadata as stated by @mgreau
  • This image might be declinated on different Linux distribution bases (aka. asciidoctor/asciidoctor-box:1.0.0 is the same as asciidoctor/asciidoctor-box:1.0.0-alpine, but there might be also asciidoctor/asciidoctor-box:1.0.0-debianfor example)

Advises @cexbrayat @mojavelinux @mgreau? Would it solve your use cases?

[cexbrayat]

I like it 👍

[mojavelinux]

I like it too. I think it solves the problem of how much to put in the image. On the one hand, you have a nice base image for anyone to extend. On the other hand, it just has the whole toolchain, and that's great for trying out the ecosystem or just using all of it.

[rfdonnelly]

Yes, please.

Using latest has broken my document build twice now. Once due to an asciidoctor-pdf upgrade and the most recent due to removal of pygments. These changes are great but it is frustrating to have no control over receiving them. Having tagged releases would allow the user to decide when to absorb breaking changes.

It would be nice to have a tagged release sooner rather than later. IMHO this GitHub issue is too large in scope. It covers both tags and base+fat images. What do you think about focusing on tags first? What do you think about creating a tag today using https://calver.org/ E.g. asciidoctor/docker-asciidoctor:2019.09? Calendar Versioning is great for rolling releases of software ecosystems. Ubuntu is a good example here.

Thank you for your ear and for great software.

[mojavelinux]

I'm definitely in favor of tags. And those tags should follow semantic versioning. Since the image has a bunch of different software, I wouldn't try to line the numbers up with any of the software included. Just start with 1.0.0.

[dduportal]

Fair! Let's fo for the proposal formulated earlier in this topic, combined with #79:

1. Let's create a new Docker image named asciidoctor/box that will be the same as the current asciidoctor/docker-asciidoctor
2. Once built and pushed: let's use the tag asciidoctor/box:1.0.0 and apply a "release management policy"

at first step, WDYT?

(next step would be creating asciidoctor/asciidoctor as a ligthweight image, same release policy, except focused only on asciidoctor alone + communicationg/documenting the depreciation policy).

[rfdonnelly]

Sounds great to me!

[rfdonnelly]

I noticed asciidoctor/box:0.1.0 has been published! Is it ready to use or should I wait for the 1.0.0 tag?

[bcouetil]

I'm really looking forward to this, to have consistent results among my organization.

Thank you for everything 😄

[dduportal]

Thanks for the heads up @bcouetil ! As a short term solution (while this item is worked on) do not hesitate to use Docker image's digests so you're sure the behavior is fixed (and no Man in the middle attack can be done on your docker image content :) ).

[dduportal]

@rfdonnelly

I noticed asciidoctor/box:0.1.0 has been published! Is it ready to use or should I wait for the 1.0.0 tag?

This was an experiment, upcoming work on it is coming: wait for this issue to be updated

[dduportal]

The PR #128 had been opened for the "tags/release" process.

Please note that the asciidoctor/box image will be managed as part of #79.

[dduportal]

First release 1.0.0:

• Github Release (+tag): https://github.com/asciidoctor/docker-asciidoctor/releases/tag/1.0.0
• Docker Hub Tag: https://hub.docker.com/layers/asciidoctor/docker-asciidoctor/1.0.0/images/sha256-5560db1f2b471665118626c783460224649f926343406a872b589c1b675a665b

[bcouetil]

You rock, many thanks 😆