From d34f776d06a24aa028dbb1c4f9ceace357f5381e Mon Sep 17 00:00:00 2001 From: Damien Duportal Date: Sat, 7 Dec 2024 14:56:20 +0100 Subject: [PATCH 1/3] docs: improve contribution guide Signed-off-by: Damien Duportal --- CONTRIBUTING.adoc | 115 ++++++++++++++++++++++++++++++ README.adoc | 60 +--------------- README.md | 176 ++++++++++++++++++---------------------------- 3 files changed, 184 insertions(+), 167 deletions(-) create mode 100644 CONTRIBUTING.adoc diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..d08e40c --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,115 @@ += Contributing to the Asciidoctor Docker Container +:source-highlighter: coderay + +== Requirements + +You need the following tools: + +* A bash compliant command line +* link:http://man7.org/linux/man-pages/man1/make.1.html[GNU make] +* link:https://github.com/sstephenson/bats[Bats] installed and in your bash PATH +* Docker installed and in your path +* link:https://github.com/aquasecurity/trivy[Trivy] cli in case you want to scan images for vulnerabilities + +== How to build and test? + +* Bats is used as a test suite runner. Since the ability to build is one way of testing, it is included. + +* You just have to run the Bats test suite, from the repository root: ++ +[source,bash] +---- +make test +---- + +=== Include test in your build pipeline or test manually + +You can use Bats directly to test the image. +Optionally, you can specify a custom image name: + +[source,bash] +---- +# If you want to use a custom name for the image, OPTIONAL +export DOCKER_IMAGE_NAME_TO_TEST=your-image-name +bats tests/*.bats +---- + +=== How to add a dependency? + +Adding a dependency/new feature follows this process: + +* An issue is usually recommended to explain the rationale of adding this new dependency with: +** Describing the feature is helps to provide to end users +** Evaluating the size of this new dependency is a good thing to help maintainers +** Links to the added project to help maintainer check and understand the underlying project (licensing, lifecycle, etc.) + +* Then, a pull request mentioning the issue above is required with changes described below + +* If the pull request is approved by the maintainers and merged to the principal branch: +** An automatic release of the image with the `latest` tag will be published to the DockerHub in the hour following the pull request merge +** A new release version of the image will be performed by a maintainers in the next hours or days, and automatically published with the same tag on the DockerHub + +The pull request is expecting the following mandatory changes: + +* The dependency is added in the link:https://github.com/asciidoctor/docker-asciidoctor/blob/main/Dockerfile[`Dockerfile`] + +* The dependency version must be pinned in different files: +** In the link:https://github.com/asciidoctor/docker-asciidoctor/blob/2beff3ac5fef10d1b4c7507f4b84d31e0b479657/Dockerfile#L94-L120[`Dockerfile`] both as a build argument (`ARG`) to allow build time override, and as an environment variable (`ENV`) to provide value to user when running containers +** In the link:https://github.com/asciidoctor/docker-asciidoctor/blob/main/README.adoc[Asciidoctor formatted README] as a link:https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes/[`Asciidcotr Document Attribute] +** In the link:https://github.com/asciidoctor/docker-asciidoctor/blob/main/tests/asciidoctor.bats[Bats Test Harness] as an environment variable so that any test case can use the value + +* One (or many) test case(s) must be added in the link:https://github.com/asciidoctor/docker-asciidoctor/blob/main/tests/asciidoctor.bats[Bats Test Harness] +** The link:https://github.com/asciidoctor/docker-asciidoctor/tree/main/tests/fixtures[Test Fixtures Directory] may be used to store `.adoc` files to support your test cases + +* It is recommended not to update the `README.md` (Markdown file): there is an automated process expected to take care of this step + +Once the pull request is merged, you may produces a second pull request to add an link:https://www.updatecli.io/[updatecli] manifest tracking the version of the newly added dependency. +Of course this is not mandatory and should not block your contribution in any ways: maintainers are the expected fallback if you cannot or do not want to produce this second change. + +=== How to bump a dependency? + +Dependencies of the image (operating system, packages, Asciidoctor projects, etc.) are tracked using link:https://www.updatecli.io/[updatecli]. +Once a day, a GitHub Action workflow link:https://github.com/asciidoctor/docker-asciidoctor/blob/main/.github/workflows/updatecli.yml[`updatecli.yaml`] is executed and opens pull requests if a new dependency can be bumped. + +The list of tracked dependencies can be found in link:https://github.com/asciidoctor/docker-asciidoctor/tree/main/updatecli/updatecli.d[]. +Each YAML file maps to a given dependency and the section `targets` list each file modified on each version bump. + +If you are a maintainer of any of these dependencies and want it to be bumped: + +* Usual process is to wait 24 hours after you've released your project: the automatic pull request should be created, and approved/merged/released by maintainers +* If the update is time-bound, you can either: +** Open the pull request yourself, by running the following `updatecli` command on your machine with your own GitHub token: ++ +[source,bash] +-- +export UPDATECLI_GITHUB_TOKEN=xxxxx +updatecli apply --values ./updatecli/values.yaml --config ./updatecli/updatecli.d/ +-- + +** Open the pull request yourself by updating the files manually. The list of files can be found in the related `updatecli``related manifest. + + +=== How to scan for vulnerabilities? + +* Trivy scans a docker image looking for software versions containing known vulnerabilities (CVEs). +It's always a good idea to scan the image to ensure no new issues are introduced. + +* Run the following command to replicate the repo's `CVE Scan` pipeline on an image build locally. +Note the pipeline runs nightly on the latest release version, so it can display issues solved in main branch. ++ +[source,bash] +---- +trivy image --severity HIGH,CRITICAL asciidoctor:latest +---- + +=== Deploy + +The goal for deploying is to make the Docker image available with the correct Docker tag in Docker Hub. + +As a matter of trust and transparency for the end-users, the image is rebuilt by Docker Hub itself by triggering a build. +This only works under the hypothesis of a minimalistic variation between the Docker build in the CI, and the Docker build by Docker Hub. + +Deploying the image requires setting the following environment variables: `DOCKERHUB_SOURCE_TOKEN` and `DOCKERHUB_TRIGGER_TOKEN`. +Their values come from a Docker Hub trigger URL: `https://hub.docker.com/api/build/v1/source/${DOCKERHUB_SOURCE_TOKEN}/trigger/${DOCKERHUB_TRIGGER_TOKEN}/call/`. + +You might want to set these variables as secret values in your CI to avoid any leaking in the output (as `curl` output for instance). diff --git a/README.adoc b/README.adoc index 12c3dd6..dcb6705 100644 --- a/README.adoc +++ b/README.adoc @@ -132,62 +132,4 @@ podman run --rm -v $(pwd):/documents/ docker.io/asciidoctor/docker-asciidoctor a == How to contribute / do it yourself? -=== Requirements - -You need the following tools: - -* A bash compliant command line -* link:http://man7.org/linux/man-pages/man1/make.1.html[GNU make] -* link:https://github.com/sstephenson/bats[Bats] installed and in your bash PATH -* Docker installed and in your path -* link:https://github.com/aquasecurity/trivy[Trivy] cli in case you want to scan images for vulnerabilities - -=== How to build and test? - -* Bats is used as a test suite runner. Since the ability to build is one way of testing, it is included. - -* You just have to run the Bats test suite, from the repository root: -+ -[source,bash] ----- -make test ----- - -==== Include test in your build pipeline or test manually - -You can use Bats directly to test the image. -Optionally, you can specify a custom image name: - -[source,bash] ----- -# If you want to use a custom name for the image, OPTIONAL -export DOCKER_IMAGE_NAME_TO_TEST=your-image-name -bats tests/*.bats ----- - -=== How to scan for vulnerabilities? - -* Trivy scans a docker image looking for software versions containing known vulnerabilities (CVEs). -It's always a good idea to scan the image to ensure no new issues are introduced. - -* Run the following command to replicate the repo's `CVE Scan` pipeline on an image build locally. -Note the pipeline runs nightly on the latest release version, so it can display issues solved in main branch. -+ -[source,bash] ----- -trivy image --severity HIGH,CRITICAL asciidoctor:latest ----- - - - -==== Deploy - -The goal for deploying is to make the Docker image available with the correct Docker tag in Docker Hub. - -As a matter of trust and transparency for the end-users, the image is rebuilt by Docker Hub itself by triggering a build. -This only works under the hypothesis of a minimalistic variation between the Docker build in the CI, and the Docker build by Docker Hub. - -Deploying the image requires setting the following environment variables: `DOCKERHUB_SOURCE_TOKEN` and `DOCKERHUB_TRIGGER_TOKEN`. -Their values come from a Docker Hub trigger URL: `https://hub.docker.com/api/build/v1/source/${DOCKERHUB_SOURCE_TOKEN}/trigger/${DOCKERHUB_TRIGGER_TOKEN}/call/`. - -You might want to set these variables as secret values in your CI to avoid any leaking in the output (as `curl` output for instance). +Check the link:https://github.com/asciidoctor/docker-asciidoctor/blob/main/CONTRIBUTING.adoc[Contributing to the Asciidoctor Docker Container] page. diff --git a/README.md b/README.md index 0437511..4c800d3 100644 --- a/README.md +++ b/README.md @@ -4,158 +4,118 @@ This Docker image provides: -- [Asciidoctor](https://asciidoctor.org/) 2.0.21 +- [Asciidoctor](https://asciidoctor.org/) 2.0.23 -- [Asciidoctor Diagram](https://asciidoctor.org/docs/asciidoctor-diagram/) 2.3.0 with ERD and Graphviz integration (supports plantuml and graphiz diagrams) +- [Asciidoctor Diagram](https://asciidoctor.org/docs/asciidoctor-diagram/) 2.3.1 with ERD and Graphviz integration (supports plantuml and graphiz diagrams) -- [Asciidoctor PDF](https://asciidoctor.org/docs/asciidoctor-pdf/) 2.3.13 +- [Asciidoctor PDF](https://asciidoctor.org/docs/asciidoctor-pdf/) 2.3.19 -- [Asciidoctor EPUB3](https://asciidoctor.org/docs/asciidoctor-epub3/) 2.1.0 +- [Asciidoctor EPUB3](https://asciidoctor.org/docs/asciidoctor-epub3/) 2.1.3 -- [Asciidoctor FB2](https://github.com/asciidoctor/asciidoctor-fb2/) 0.7.0 +- [Asciidoctor FB2](https://github.com/asciidoctor/asciidoctor-fb2/) 0.7.0 -- [Asciidoctor Mathematical](https://github.com/asciidoctor/asciidoctor-mathematical) 0.3.5 +- [Asciidoctor Mathematical](https://github.com/asciidoctor/asciidoctor-mathematical) 0.3.5 -- [Asciidoctor reveal.js](https://docs.asciidoctor.org/reveal.js-converter/latest/) 5.2.0 +- [Asciidoctor reveal.js](https://docs.asciidoctor.org/reveal.js-converter/latest/) 5.2.0 -- [AsciiMath](https://rubygems.org/gems/asciimath) +- [AsciiMath](https://rubygems.org/gems/asciimath) -- Source highlighting using [Rouge](http://rouge.jneen.net), [CodeRay](https://rubygems.org/gems/coderay) or [Pygments](https://pygments.org/) +- Source highlighting using [Rouge](http://rouge.jneen.net), [CodeRay](https://rubygems.org/gems/coderay) or [Pygments](https://pygments.org/) -- [Asciidoctor Confluence](https://github.com/asciidoctor/asciidoctor-confluence) 0.0.2 +- [Asciidoctor Confluence](https://github.com/asciidoctor/asciidoctor-confluence) 0.0.2 -- [Asciidoctor Bibtex](https://github.com/asciidoctor/asciidoctor-bibtex) 0.9.0 +- [Asciidoctor Bibtex](https://github.com/asciidoctor/asciidoctor-bibtex) 0.9.0 -- [Asciidoctor Kroki](https://github.com/Mogztter/asciidoctor-kroki) 0.9.1 +- [Asciidoctor Kroki](https://github.com/Mogztter/asciidoctor-kroki) 0.10.0 -- [Asciidoctor Reducer](https://github.com/asciidoctor/asciidoctor-reducer) 1.0.2 +- [Asciidoctor Reducer](https://github.com/asciidoctor/asciidoctor-reducer) 1.0.2 -This image uses Alpine Linux 3.19.1 as base image. +This image uses Alpine Linux 3.21.0 as base image. -
+> [!NOTE] +> Docker Engine [20.10](https://docs.docker.com/engine/release-notes/#20100) or later is required (or any container engine supporting [Alpine 3.14](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.14.0)) to avoid unexpected `No such file or directory` errors (such as [\#214](https://github.com/asciidoctor/docker-asciidoctor/issues/214) or [\#215](https://github.com/asciidoctor/docker-asciidoctor/issues/215)). -Docker Engine [20.10](https://docs.docker.com/engine/release-notes/#20100) or later is required (or any container engine supporting [Alpine 3.14](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.14.0)) to avoid unexpected `No such file or directory` errors (such as [\#214](https://github.com/asciidoctor/docker-asciidoctor/issues/214) or [\#215](https://github.com/asciidoctor/docker-asciidoctor/issues/215)). - -
- -
- -This image uses the Go-based [erd-go](https://github.com/kaishuu0123/erd-go/) instead of the original Haskell-based [erd](https://github.com/BurntSushi/erd) to allow the Docker image to be provided as a multi-platform image. - -
+> [!NOTE] +> This image uses the Go-based [erd-go](https://github.com/kaishuu0123/erd-go/) instead of the original Haskell-based [erd](https://github.com/BurntSushi/erd) to allow the Docker image to be provided as a multi-platform image. ## How to use it Just run: - docker run -it -u $(id -u):$(id -g) -v :/documents/ asciidoctor/docker-asciidoctor +``` bash +docker run -it -u $(id -u):$(id -g) -v :/documents/ asciidoctor/docker-asciidoctor +``` or the following for [Podman](https://podman.io/): - podman run -it -v :/documents/ docker.io/asciidoctor/docker-asciidoctor +``` bash +podman run -it -v :/documents/ docker.io/asciidoctor/docker-asciidoctor +``` -Docker/Podman maps your directory with */documents* directory in the container. +Docker/Podman maps your directory with */documents* directory in the container. -
- -You might need to add the option `:z` or `:Z` like `:/documents/:z` or `:/documents/:Z` if you are using SELinux. See [Docker docs](https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label) or [Podman docs](https://docs.podman.io/en/latest/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options). - -
+> [!NOTE] +> You might need to add the option `:z` or `:Z` like `:/documents/:z` or `:/documents/:Z` if you are using SELinux. See [Docker docs](https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label) or [Podman docs](https://docs.podman.io/en/latest/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options). After you start the container, you can use Asciidoctor commands to convert AsciiDoc files that you created in the directory mentioned above. You can find several examples below. -- To run Asciidoctor on a basic AsciiDoc file: +- To run Asciidoctor on a basic AsciiDoc file: - asciidoctor sample.adoc - asciidoctor-pdf sample.adoc - asciidoctor-epub3 sample.adoc + ``` bash + asciidoctor sample.adoc + asciidoctor-pdf sample.adoc + asciidoctor-epub3 sample.adoc + ``` -- To run AsciiDoc on an AsciiDoc file that contains diagrams: +- To run AsciiDoc on an AsciiDoc file that contains diagrams: - asciidoctor -r asciidoctor-diagram sample-with-diagram.adoc - asciidoctor-pdf -r asciidoctor-diagram sample-with-diagram.adoc - asciidoctor-epub3 -r asciidoctor-diagram sample-with-diagram.adoc + ``` bash + asciidoctor -r asciidoctor-diagram sample-with-diagram.adoc + asciidoctor-pdf -r asciidoctor-diagram sample-with-diagram.adoc + asciidoctor-epub3 -r asciidoctor-diagram sample-with-diagram.adoc + ``` -- To run AsciiDoc on an AsciiDoc file that contains latexmath and stem blocks: +- To run AsciiDoc on an AsciiDoc file that contains latexmath and stem blocks: - asciidoctor -r asciidoctor-mathematical sample-with-diagram.adoc - asciidoctor-pdf -r asciidoctor-mathematical sample-with-diagram.adoc - asciidoctor-epub3 -r asciidoctor-mathematical sample-with-diagram.adoc + ``` bash + asciidoctor -r asciidoctor-mathematical sample-with-diagram.adoc + asciidoctor-pdf -r asciidoctor-mathematical sample-with-diagram.adoc + asciidoctor-epub3 -r asciidoctor-mathematical sample-with-diagram.adoc + ``` -- To use Asciidoctor Confluence: +- To use Asciidoctor Confluence: - asciidoctor-confluence --host HOSTNAME --spaceKey SPACEKEY --title TITLE --username USER --password PASSWORD sample.adoc + ``` bash + asciidoctor-confluence --host HOSTNAME --spaceKey SPACEKEY --title TITLE --username USER --password PASSWORD sample.adoc + ``` -- To use Asciidoctor reveal.js with local downloaded reveal.js: +- To use Asciidoctor reveal.js with local downloaded reveal.js: - asciidoctor-revealjs sample-slides.adoc - asciidoctor-revealjs -r asciidoctor-diagram sample-slides.adoc + ``` bash + asciidoctor-revealjs sample-slides.adoc + asciidoctor-revealjs -r asciidoctor-diagram sample-slides.adoc + ``` -- To use Asciidoctor reveal.js with online reveal.js: +- To use Asciidoctor reveal.js with online reveal.js: - asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 sample-slides.adoc - asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 -r asciidoctor-diagram sample-slides.adoc + ``` bash + asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 sample-slides.adoc + asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 -r asciidoctor-diagram sample-slides.adoc + ``` -- To convert files in batch: +- To convert files in batch: - docker run --rm -u $(id -u):$(id -g) -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf index.adoc + ``` bash + docker run --rm -u $(id -u):$(id -g) -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf index.adoc + ``` - or: + or: - podman run --rm -v $(pwd):/documents/ docker.io/asciidoctor/docker-asciidoctor asciidoctor-pdf index.adoc + ``` bash + podman run --rm -v $(pwd):/documents/ docker.io/asciidoctor/docker-asciidoctor asciidoctor-pdf index.adoc + ``` ## How to contribute / do it yourself? -### Requirements - -You need the following tools: - -- A bash compliant command line - -- [GNU make](http://man7.org/linux/man-pages/man1/make.1.html) - -- [Bats](https://github.com/sstephenson/bats) installed and in your bash PATH - -- Docker installed and in your path - -- [Trivy](https://github.com/aquasecurity/trivy) cli in case you want to scan images for vulnerabilities - -### How to build and test? - -- Bats is used as a test suite runner. Since the ability to build is one way of testing, it is included. - -- You just have to run the Bats test suite, from the repository root: - - make test - -#### Include test in your build pipeline or test manually - -You can use Bats directly to test the image. -Optionally, you can specify a custom image name: - - # If you want to use a custom name for the image, OPTIONAL - export DOCKER_IMAGE_NAME_TO_TEST=your-image-name - bats tests/*.bats - -### How to scan for vulnerabilities? - -- Trivy scans a docker image looking for software versions containing known vulnerabilities (CVEs). - It’s always a good idea to scan the image to ensure no new issues are introduced. - -- Run the following command to replicate the repo’s `CVE Scan` pipeline on an image build locally. - Note the pipeline runs nightly on the latest release version, so it can display issues solved in main branch. - - trivy image --severity HIGH,CRITICAL asciidoctor:latest - -#### Deploy - -The goal for deploying is to make the Docker image available with the correct Docker tag in Docker Hub. - -As a matter of trust and transparency for the end-users, the image is rebuilt by Docker Hub itself by triggering a build. -This only works under the hypothesis of a minimalistic variation between the Docker build in the CI, and the Docker build by Docker Hub. - -Deploying the image requires setting the following environment variables: `DOCKERHUB_SOURCE_TOKEN` and `DOCKERHUB_TRIGGER_TOKEN`. -Their values come from a Docker Hub trigger URL: `https://hub.docker.com/api/build/v1/source/${DOCKERHUB_SOURCE_TOKEN}/trigger/${DOCKERHUB_TRIGGER_TOKEN}/call/`. - -You might want to set these variables as secret values in your CI to avoid any leaking in the output (as `curl` output for instance). +Check the [Contributing to the Asciidoctor Docker Container](https://github.com/asciidoctor/docker-asciidoctor/blob/main/CONTRIBUTING.adoc) page. From d08aba00d5ebe2eb1b2af145a26bacd781d97df1 Mon Sep 17 00:00:00 2001 From: Damien Duportal Date: Sat, 7 Dec 2024 15:33:12 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Guillaume Grossetie --- CONTRIBUTING.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index d08e40c..fb22c5c 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -8,8 +8,8 @@ You need the following tools: * A bash compliant command line * link:http://man7.org/linux/man-pages/man1/make.1.html[GNU make] * link:https://github.com/sstephenson/bats[Bats] installed and in your bash PATH -* Docker installed and in your path -* link:https://github.com/aquasecurity/trivy[Trivy] cli in case you want to scan images for vulnerabilities +* Docker installed and in your `PATH` +* link:https://github.com/aquasecurity/trivy[Trivy] CLI in case you want to scan images for vulnerabilities == How to build and test? From 7abe922fe0486bb5d36c35ae9523588d5ff2ea37 Mon Sep 17 00:00:00 2001 From: Damien Duportal Date: Sat, 7 Dec 2024 15:43:43 +0100 Subject: [PATCH 3/3] code review Signed-off-by: Damien Duportal --- CONTRIBUTING.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index fb22c5c..6449978 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -6,7 +6,7 @@ You need the following tools: * A bash compliant command line -* link:http://man7.org/linux/man-pages/man1/make.1.html[GNU make] +* link:https://man7.org/linux/man-pages/man1/make.1.html[GNU make] * link:https://github.com/sstephenson/bats[Bats] installed and in your bash PATH * Docker installed and in your `PATH` * link:https://github.com/aquasecurity/trivy[Trivy] CLI in case you want to scan images for vulnerabilities