[PATCH] ci: fix missing Ruby dependency in "documentation" job

[PATCH] ci: fix missing Ruby dependency in "documentation" job

[Patrick Steinhardt]

Our "documentation" job has recently stopped working with the following
error:

  + sudo gem install --version 1.5.8 asciidoctor
  + gem install --version 1.5.8 asciidoctor
  ./ci/install-dependencies.sh: 23: gem: not found

The root cause of this is that we never explicitly install Ruby, and
consequently gem(1) isn't explicitly pulled inus, either. This used to
work alright because we transitively pulled in Ruby via asciidoc. But
due to an update it seems that we stopped pulling in the transitive
dependency, and consequently we don't have gem(1) available anymore.

Fix this by explicitly installing Ruby.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
Hi,

I spotted the failure yesterday. You can see that this fixes the
pipeline at [1]. Thanks!

Patrick

[1]: https://gitlab.com/gitlab-org/git/-/merge_requests/660
---
 ci/install-dependencies.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 10c3530d1a..502e518077 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -164,7 +164,7 @@ sparse)
 		libexpat-dev gettext zlib1g-dev sparse
 	;;
 Documentation)
-	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make
+	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
 
 	test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
 	sudo gem install --version 1.5.8 asciidoctor

---
base-commit: 1630431f326e15fcde608827b5ff38422528eb59
change-id: 20260901-b4-pks-ci-fix-documentation-job-e971e10fbc94

Re: [PATCH] ci: fix missing Ruby dependency in "documentation" job

[Toon Claes]

Patrick Steinhardt <ps@pks.im> writes:

> Our "documentation" job has recently stopped working with the following
> error:
>
>   + sudo gem install --version 1.5.8 asciidoctor
>   + gem install --version 1.5.8 asciidoctor
>   ./ci/install-dependencies.sh: 23: gem: not found
>
> The root cause of this is that we never explicitly install Ruby, and
> consequently gem(1) isn't explicitly pulled inus, either. This used to

"inus"?

> work alright because we transitively pulled in Ruby via asciidoc. But
> due to an update it seems that we stopped pulling in the transitive
> dependency, and consequently we don't have gem(1) available anymore.
>
> Fix this by explicitly installing Ruby.

Thanks for this fix, I was just looking at it as well, although I wasn't
sure it started failing recently.


> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> Hi,
>
> I spotted the failure yesterday. You can see that this fixes the
> pipeline at [1]. Thanks!
>
> Patrick
>
> [1]: https://gitlab.com/gitlab-org/git/-/merge_requests/660
> ---
>  ci/install-dependencies.sh | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
> index 10c3530d1a..502e518077 100755
> --- a/ci/install-dependencies.sh
> +++ b/ci/install-dependencies.sh
> @@ -164,7 +164,7 @@ sparse)
>  		libexpat-dev gettext zlib1g-dev sparse
>  	;;
>  Documentation)
> -	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make
> +	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby

Good!

>  
>  	test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
>  	sudo gem install --version 1.5.8 asciidoctor
>
> ---
> base-commit: 1630431f326e15fcde608827b5ff38422528eb59
> change-id: 20260901-b4-pks-ci-fix-documentation-job-e971e10fbc94

Thanks!

-- 
Laters,
Toon

Re: [PATCH] ci: fix missing Ruby dependency in "documentation" job

[Patrick Steinhardt]

On Tue, Sep 01, 2026 at 10:24:32AM +0200, Toon Claes wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > Our "documentation" job has recently stopped working with the following
> > error:
> >
> >   + sudo gem install --version 1.5.8 asciidoctor
> >   + gem install --version 1.5.8 asciidoctor
> >   ./ci/install-dependencies.sh: 23: gem: not found
> >
> > The root cause of this is that we never explicitly install Ruby, and
> > consequently gem(1) isn't explicitly pulled inus, either. This used to
> 
> "inus"?

Huh. I guess this was supposed to just say "in"? Fixed locally, but I'll
refrain from sending out a new version just to fix this. Thanks!

Patrick

Re: [PATCH] ci: fix missing Ruby dependency in "documentation" job

[Jeff King]

On Tue, Sep 01, 2026 at 10:16:11AM +0200, Patrick Steinhardt wrote:

> Our "documentation" job has recently stopped working with the following
> error:
> 
>   + sudo gem install --version 1.5.8 asciidoctor
>   + gem install --version 1.5.8 asciidoctor
>   ./ci/install-dependencies.sh: 23: gem: not found

Not directly related to your patch but... asciidoctor 1.5.8, really?
That version is 8 years old. Looks like we set that version in
615a6c37e1 (ci: stick with Asciidoctor v1.5.8 for now, 2019-03-29)
due to some issues with the then-new-ish v2.0.0.

But these days I'd guess everybody is using v2.0.x (which seems to work
fine) for local builds. We probably ought to do the same in CI. If we
have to catch issues in one, I'd rather it be the one people are likely
to actually use.

It's possible that we could benefit from building with both in order to
support the older version. But given its age I doubt it's worth it. We
can still take bug fixes if somebody finds a problem, but we don't
necessarily need to spend cycles building every commit with 1.5.8.

-Peff

Re: [PATCH] ci: fix missing Ruby dependency in "documentation" job

[Jeff King]

On Tue, Sep 01, 2026 at 04:47:38AM -0400, Jeff King wrote:

> Not directly related to your patch but... asciidoctor 1.5.8, really?
> That version is 8 years old. Looks like we set that version in
> 615a6c37e1 (ci: stick with Asciidoctor v1.5.8 for now, 2019-03-29)
> due to some issues with the then-new-ish v2.0.0.
> 
> But these days I'd guess everybody is using v2.0.x (which seems to work
> fine) for local builds. We probably ought to do the same in CI. If we
> have to catch issues in one, I'd rather it be the one people are likely
> to actually use.

Ah, indeed. It was fixed in f6461b82b9 (Documentation: fix build with
Asciidoctor 2, 2019-09-15). The thread here:

  https://lore.kernel.org/git/20190915212621.GV11334@genre.crustytoothpaste.net

suggests that it could be removed, but was just waiting on a few more
fixes for the v2 series. I guess nobody ever circled back around to it.

-Peff

Re: [PATCH] ci: fix missing Ruby dependency in "documentation" job

[Patrick Steinhardt]

On Tue, Sep 01, 2026 at 04:47:37AM -0400, Jeff King wrote:
> On Tue, Sep 01, 2026 at 10:16:11AM +0200, Patrick Steinhardt wrote:
> 
> > Our "documentation" job has recently stopped working with the following
> > error:
> > 
> >   + sudo gem install --version 1.5.8 asciidoctor
> >   + gem install --version 1.5.8 asciidoctor
> >   ./ci/install-dependencies.sh: 23: gem: not found
> 
> Not directly related to your patch but... asciidoctor 1.5.8, really?
> That version is 8 years old. Looks like we set that version in
> 615a6c37e1 (ci: stick with Asciidoctor v1.5.8 for now, 2019-03-29)
> due to some issues with the then-new-ish v2.0.0.
> 
> But these days I'd guess everybody is using v2.0.x (which seems to work
> fine) for local builds. We probably ought to do the same in CI. If we
> have to catch issues in one, I'd rather it be the one people are likely
> to actually use.

> It's possible that we could benefit from building with both in order to
> support the older version. But given its age I doubt it's worth it. We
> can still take bug fixes if somebody finds a problem, but we don't
> necessarily need to spend cycles building every commit with 1.5.8.

I was wondering about whether I should bump its version while at it. In
fact, we could just install it from the Ubuntu sources nowadays, too. I
ultimately decided to not do that though and just fix the failing CI
pipeline for now, but I agree that it's something we might want to
follow up on.

Patrick

[PATCH 0/2] bump ci asciidoctor version

[Jeff King]

On Tue, Sep 01, 2026 at 12:41:12PM +0200, Patrick Steinhardt wrote:

> > But these days I'd guess everybody is using v2.0.x (which seems to work
> > fine) for local builds. We probably ought to do the same in CI. If we
> > have to catch issues in one, I'd rather it be the one people are likely
> > to actually use.
> 
> > It's possible that we could benefit from building with both in order to
> > support the older version. But given its age I doubt it's worth it. We
> > can still take bug fixes if somebody finds a problem, but we don't
> > necessarily need to spend cycles building every commit with 1.5.8.
> 
> I was wondering about whether I should bump its version while at it. In
> fact, we could just install it from the Ubuntu sources nowadays, too. I
> ultimately decided to not do that though and just fix the failing CI
> pipeline for now, but I agree that it's something we might want to
> follow up on.

I think your fix kept to the minimum, which is good. I agree we should
just install it from the system package manager. I _thought_ that might
make your fix here obsolete, but we also install the concurrent-ruby
gem. That comes from 974cdca345 (doc: introduce a synopsis typesetting,
2024-09-24) which also introduced some custom ruby code in asciidoctor
extensions. But it's not clear to me why it's necessary (and I build the
docs happily on my local system without it installed). +cc Jean-Noël for
any wisdom.

I guess installing asciidoctor from Ubuntu would also bring in ruby as a
dependency. So I suppose it does make your patch obsolete, but it also
doesn't hurt to be explicit that we expect "gem install" to work.

Anyway, here is a fix for the version which can be applied on top of
ps/ci-depends-on-ruby.

-Peff

[PATCH 1/2] ci: drop ALREADY_HAVE_ASCIIDOCTOR variable

[Jeff King]

Our install-dependencies script avoids installing asciidoctor if the
CI environment claims to have it already. But the only environment which
made use of this was Azure Pipelines, which went away in 6081d3898f (ci:
retire the Azure Pipelines definition, 2020-04-11). So this conditional
was effectively doing nothing. Let's clean it up.

Signed-off-by: Jeff King <peff@peff.net>
---
 ci/install-dependencies.sh | 1 -
 1 file changed, 1 deletion(-)

diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 502e518077..2f61fbb07c 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -166,7 +166,6 @@ sparse)
 Documentation)
 	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
 
-	test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
 	sudo gem install --version 1.5.8 asciidoctor
 	sudo gem install concurrent-ruby
 	;;
-- 
2.55.0.1074.gcd259ea853

[PATCH 2/2] ci: use system asciidoctor

[Jeff King]

Our CI Documentation builds have pinned asciidoctor since 615a6c37e1
(ci: stick with Asciidoctor v1.5.8 for now, 2019-03-29). Back then a few
changes were needed to build with the then-new v2.0.0.

We've since made those changes, in f6461b82b9 (Documentation: fix build
with Asciidoctor 2, 2019-09-15) and other commits. So it is not only
safe to use newer versions of asciidoctor, but preferable: it's what
people are likely to use for actually building the documentation in
practice!

I don't think there's any need to pin to a specific version. We can just
use what ships in our Ubuntu image, which should give us an arbitrary
representative version (and if it changes and something breaks, we'd
want to know).

Signed-off-by: Jeff King <peff@peff.net>
---
Confirmed that this successfully ran CI via GitHub Actions. Looks like
the image there uses asciidoctor 2.0.20, which seems reasonable (it's
from 2023, but stable images tend to lag about that much).

 ci/install-dependencies.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 2f61fbb07c..d57dce5663 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -164,9 +164,9 @@ sparse)
 		libexpat-dev gettext zlib1g-dev sparse
 	;;
 Documentation)
-	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
+	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby \
+		asciidoctor
 
-	sudo gem install --version 1.5.8 asciidoctor
 	sudo gem install concurrent-ruby
 	;;
 esac
-- 
2.55.0.1074.gcd259ea853

Re: [PATCH 2/2] ci: use system asciidoctor

[Patrick Steinhardt]

On Wed, Sep 02, 2026 at 03:16:13AM -0400, Jeff King wrote:
> Our CI Documentation builds have pinned asciidoctor since 615a6c37e1
> (ci: stick with Asciidoctor v1.5.8 for now, 2019-03-29). Back then a few
> changes were needed to build with the then-new v2.0.0.
> 
> We've since made those changes, in f6461b82b9 (Documentation: fix build
> with Asciidoctor 2, 2019-09-15) and other commits. So it is not only
> safe to use newer versions of asciidoctor, but preferable: it's what
> people are likely to use for actually building the documentation in
> practice!
> 
> I don't think there's any need to pin to a specific version. We can just
> use what ships in our Ubuntu image, which should give us an arbitrary
> representative version (and if it changes and something breaks, we'd
> want to know).

Makes sense.

One thing that we might have to worry about is compatibility with _old_
versions of asciidoctor. Now that we're using a more modern version of
it we might start relying on features that weren't available in older
versions, and we wouldn't notice anymore. So we kind of have the reverse
problem now.

The best-case scenario would be if asciidoctor had something like a
compatibility mode where you can ask it to complain about features that
aren't available in a specific cutoff version. But I have no idea
whether such a thing even exists.

Also, I'm not sure though whether this concern is something that we
really have to care about, I may be overthinking this quite a bit. So
please don't read this as a "Let's not use a modern version", but rather
as me writing down my unfiltered thoughts.

>  ci/install-dependencies.sh | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
> index 2f61fbb07c..d57dce5663 100755
> --- a/ci/install-dependencies.sh
> +++ b/ci/install-dependencies.sh
> @@ -164,9 +164,9 @@ sparse)
>  		libexpat-dev gettext zlib1g-dev sparse
>  	;;
>  Documentation)
> -	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
> +	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby \
> +		asciidoctor
>  
> -	sudo gem install --version 1.5.8 asciidoctor
>  	sudo gem install concurrent-ruby

Huh. I was wondering whether we can now stop installing Ruby altogether,
but we still install the "concurrent-ruby" Gem. But what even is that,
and what do we use it for?

It's originally been introduced via 974cdca345 (doc: introduce a
synopsis typesetting, 2024-09-24), but unfortunately the commit message
does not document why we have to install that Gem now. I couldn't find
any reasoning in the mailing list thread, either.

Patrick

Re: [PATCH 2/2] ci: use system asciidoctor

[Jeff King]

On Wed, Sep 02, 2026 at 09:55:49AM +0200, Patrick Steinhardt wrote:

> One thing that we might have to worry about is compatibility with _old_
> versions of asciidoctor. Now that we're using a more modern version of
> it we might start relying on features that weren't available in older
> versions, and we wouldn't notice anymore. So we kind of have the reverse
> problem now.

Right, this is the "we could in theory check both" path I mentioned
earlier.

v1.5.8 is sufficiently old that I don't think we need to care anymore.
We can still take bug reports if somebody happens to use it and finds a
problem. Checking other older versions isn't likely to be that
interesting (the next version after 1.5.8 is 2.0.0, which had a higher
than usual chance of breaking things).

> >  Documentation)
> > -	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
> > +	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby \
> > +		asciidoctor
> >  
> > -	sudo gem install --version 1.5.8 asciidoctor
> >  	sudo gem install concurrent-ruby
> 
> Huh. I was wondering whether we can now stop installing Ruby altogether,
> but we still install the "concurrent-ruby" Gem. But what even is that,
> and what do we use it for?
> 
> It's originally been introduced via 974cdca345 (doc: introduce a
> synopsis typesetting, 2024-09-24), but unfortunately the commit message
> does not document why we have to install that Gem now. I couldn't find
> any reasoning in the mailing list thread, either.

Er, yeah, see my cover letter. :)

-Peff

Re: [PATCH 2/2] ci: use system asciidoctor

[Patrick Steinhardt]

On Wed, Sep 02, 2026 at 05:01:46AM -0400, Jeff King wrote:
> On Wed, Sep 02, 2026 at 09:55:49AM +0200, Patrick Steinhardt wrote:
> 
> > One thing that we might have to worry about is compatibility with _old_
> > versions of asciidoctor. Now that we're using a more modern version of
> > it we might start relying on features that weren't available in older
> > versions, and we wouldn't notice anymore. So we kind of have the reverse
> > problem now.
> 
> Right, this is the "we could in theory check both" path I mentioned
> earlier.
> 
> v1.5.8 is sufficiently old that I don't think we need to care anymore.
> We can still take bug reports if somebody happens to use it and finds a
> problem. Checking other older versions isn't likely to be that
> interesting (the next version after 1.5.8 is 2.0.0, which had a higher
> than usual chance of breaking things).

Yeah, I agree. We can still reconsider if we ever hit a scenario where
it caused problems after all.

> > >  Documentation)
> > > -	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
> > > +	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby \
> > > +		asciidoctor
> > >  
> > > -	sudo gem install --version 1.5.8 asciidoctor
> > >  	sudo gem install concurrent-ruby
> > 
> > Huh. I was wondering whether we can now stop installing Ruby altogether,
> > but we still install the "concurrent-ruby" Gem. But what even is that,
> > and what do we use it for?
> > 
> > It's originally been introduced via 974cdca345 (doc: introduce a
> > synopsis typesetting, 2024-09-24), but unfortunately the commit message
> > does not document why we have to install that Gem now. I couldn't find
> > any reasoning in the mailing list thread, either.
> 
> Er, yeah, see my cover letter. :)

D'oh, yeah. I somehow skipped reading the cover letter altogether,
sorry.

Patrick

Re: [PATCH 2/2] ci: use system asciidoctor

[Jeff King]

On Wed, Sep 02, 2026 at 11:59:38AM +0200, Patrick Steinhardt wrote:

> On Wed, Sep 02, 2026 at 05:01:46AM -0400, Jeff King wrote:
> > On Wed, Sep 02, 2026 at 09:55:49AM +0200, Patrick Steinhardt wrote:
> > 
> > > One thing that we might have to worry about is compatibility with _old_
> > > versions of asciidoctor. Now that we're using a more modern version of
> > > it we might start relying on features that weren't available in older
> > > versions, and we wouldn't notice anymore. So we kind of have the reverse
> > > problem now.
> > 
> > Right, this is the "we could in theory check both" path I mentioned
> > earlier.
> > 
> > v1.5.8 is sufficiently old that I don't think we need to care anymore.
> > We can still take bug reports if somebody happens to use it and finds a
> > problem. Checking other older versions isn't likely to be that
> > interesting (the next version after 1.5.8 is 2.0.0, which had a higher
> > than usual chance of breaking things).
> 
> Yeah, I agree. We can still reconsider if we ever hit a scenario where
> it caused problems after all.

BTW, after having dug into Debian versioning for another patch this
morning, I bothered to look at which asciidoctors they ship. Even Debian
11, which just went out of LTS, was on asciidoctor 2.x. Ditto for RHEL8,
which has a 10-year cycle (it hasn't been 10 years since asciidoctor
2.0.0, but it luckily was released in the right part of the cycle).

I don't think that changes our conclusions. Just adding a little bit of
research for posterity.

-Peff

Re: [PATCH 2/2] ci: use system asciidoctor

[Todd Zullinger]

Jeff King wrote:
> BTW, after having dug into Debian versioning for another
> patch this morning, I bothered to look at which
> asciidoctors they ship. Even Debian 11, which just went
> out of LTS, was on asciidoctor 2.x. Ditto for RHEL8, which
> has a 10-year cycle (it hasn't been 10 years since
> asciidoctor 2.0.0, but it luckily was released in the
> right part of the cycle).

FWIW, asciidoctor in RHEL and clones is part of the add-on
EPEL repo from the Fedora project.

Being part of EPEL rather than the base RHEL is largely why
the version bumps happen in what is otherwise a relatively
static base OS -- EPEL is run by volunteers and allows for
pushing breaking changes a bit more liberally than RHEL
itself.

(Asking free laborers to be on the hook for backporting bug
and security fixes for 10 years doesn't go down all that
well, unsurprisingly.)

Looking at the Fedora/EPEL asciidoctor commit history¹, it
looks like I pushed commits to bring it up to 2.0.20 for
EL-9² before I stopped contributing.  Those changes have
never been pushed out though, so it doesn't look like
anyone's really minding the ascidoctor packages in EPEL
these days.

¹ https://src.fedoraproject.org/rpms/rubygem-asciidoctor
² https://src.fedoraproject.org/rpms/rubygem-asciidoctor/commits/epel9

As none of the CI jobs are installing documentation against
any RHEL-like targets, this doesn't matter much.  But if we
were, we'd need to install the 'epel-release' package before
installing asciidoctor, perhaps something like this:

  diff --git i/ci/install-dependencies.sh w/ci/install-dependencies.sh
  index 10c3530d1a..119e12041d 100755
  --- i/ci/install-dependencies.sh
  +++ w/ci/install-dependencies.sh
  @@ -32,6 +32,10 @@ alpine-*)
   		bash cvs gnupg perl-cgi perl-dbd-sqlite perl-io-tty cargo >/dev/null
   	;;
   fedora-*|almalinux-*)
  +	case "$distro" in
  +	almalinux-*)
  +		dnf -yq install epel-release >/dev/null
  +	esac
   	case "$jobname" in
   	*-meson)
   		MESON_DEPS="meson ninja";;

> I don't think that changes our conclusions. Just adding a
> little bit of research for posterity.

Ditto. ;)

I'm happy to see more Asciidoctor support.  It seems to
produce moderately better output than Asciidoc, in my
experience.  Though I admit I haven't looked closely at
Asciidoc after development picked back up a little to add
Python 3 support and keep the project going.

-- 
Todd

Re: [PATCH 2/2] ci: use system asciidoctor

[Jeff King]

On Sat, Sep 05, 2026 at 11:23:00AM -0400, Todd Zullinger wrote:

> As none of the CI jobs are installing documentation against
> any RHEL-like targets, this doesn't matter much.  But if we
> were, we'd need to install the 'epel-release' package before
> installing asciidoctor, perhaps something like this:

Thanks, that's good to know, though I hope we'll never need to use it
the information. :)

> I'm happy to see more Asciidoctor support.  It seems to
> produce moderately better output than Asciidoc, in my
> experience.  Though I admit I haven't looked closely at
> Asciidoc after development picked back up a little to add
> Python 3 support and keep the project going.

Yeah, I think we were ready (mentally at least) to transition when it
looked like asciidoc was unmaintained. The dual-tool system does
occasionally introduce extra work, but I don't know if there would be
downsides to dropping support for asciidoc now. Presumably the biggest
risk would be losing support for some platforms, though in general it's
not the end of the world to pull in pre-formatted pages on such systems.

I'll leave exploring that for another day.

-Peff

[PATCH (RESEND)] ci: use system asciidoctor

[Tuomas Ahola]

From: Jeff King <peff@peff.net>

Our CI Documentation builds have pinned asciidoctor since 615a6c37e1
(ci: stick with Asciidoctor v1.5.8 for now, 2019-03-29). Back then a few
changes were needed to build with the then-new v2.0.0.

We've since made those changes, in f6461b82b9 (Documentation: fix build
with Asciidoctor 2, 2019-09-15) and other commits. So it is not only
safe to use newer versions of asciidoctor, but preferable: it's what
people are likely to use for actually building the documentation in
practice!

I don't think there's any need to pin to a specific version. We can just
use what ships in our Ubuntu image, which should give us an arbitrary
representative version (and if it changes and something breaks, we'd
want to know).

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---

Notes:
    The release notes draft for v2.56.0 already claims that asciidoctor
    has been updated to be installed via the system package manager.
    Clearly it refers to this patch which isn't, however, anywhere near
    the master branch.

 ci/install-dependencies.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 2f61fbb07c..d57dce5663 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -164,9 +164,9 @@ sparse)
 		libexpat-dev gettext zlib1g-dev sparse
 	;;
 Documentation)
-	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
+	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby \
+		asciidoctor
 
-	sudo gem install --version 1.5.8 asciidoctor
 	sudo gem install concurrent-ruby
 	;;
 esac
-- 
jk/ci-use-system-asciidoctor-for-real

Re: [PATCH (RESEND)] ci: use system asciidoctor

[Jeff King]

On Fri, Sep 11, 2026 at 10:52:50PM +0300, Tuomas Ahola wrote:

>     The release notes draft for v2.56.0 already claims that asciidoctor
>     has been updated to be installed via the system package manager.
>     Clearly it refers to this patch which isn't, however, anywhere near
>     the master branch.

I was confused about what was going on from this description, and why
patch 1/2 is not mentioned here. But reading the "What's cooking"
conversation, I think it is simply: this patch was missed when picking
up the jk/ci-use-system-asciidoctor topic.

Possibly because the lead-in patch from Patrick got duplicated (I notice
that jk/ci-use-system-asciidoctor is not based on ps/ci-depends-on-ruby).
But whatever the reason, this was supposed to go on top of the jk/
topic branch.

Thanks for noticing.

-Peff

Re: [PATCH (RESEND)] ci: use system asciidoctor

[Junio C Hamano]

Tuomas Ahola <taahol@utu.fi> writes:

> Notes:
>     The release notes draft for v2.56.0 already claims that asciidoctor
>     has been updated to be installed via the system package manager.
>     Clearly it refers to this patch which isn't, however, anywhere near
>     the master branch.

I think the description was added to the release notes in 47ce80527c
(A bit more for -rc1, 2026-09-11), one integration cycle after the
2.56-rc0 was tagged.  This patch and Patrick's "gem" patch were
merged between 2.56-rc0 and 47ce80527c (aka "today's master").

So there is nothing to see here, I think.

Re: [PATCH (RESEND)] ci: use system asciidoctor

[Tuomas Ahola]

Junio C Hamano <gitster@pobox.com> wrote:

> Tuomas Ahola <taahol@utu.fi> writes:
> 
> > Notes:
> >     The release notes draft for v2.56.0 already claims that asciidoctor
> >     has been updated to be installed via the system package manager.
> >     Clearly it refers to this patch which isn't, however, anywhere near
> >     the master branch.
> 
> I think the description was added to the release notes in 47ce80527c
> (A bit more for -rc1, 2026-09-11), one integration cycle after the
> 2.56-rc0 was tagged.  This patch and Patrick's "gem" patch were
> merged between 2.56-rc0 and 47ce80527c (aka "today's master").
> 
> So there is nothing to see here, I think.

These two were indeed merged:

* 4340a709bf (ci: fix missing Ruby dependency in "documentation" job, 2026-09-01)
* 1c1eed13bd (ci: drop ALREADY_HAVE_ASCIIDOCTOR variable, 2026-09-02)

But this is a third one (ci: use system asciidoctor)---it seems it was never
picked up.

Re: [PATCH (RESEND)] ci: use system asciidoctor

[Junio C Hamano]

Tuomas Ahola <taahol@utu.fi> writes:

> These two were indeed merged:
>
> * 4340a709bf (ci: fix missing Ruby dependency in "documentation" job, 2026-09-01)
> * 1c1eed13bd (ci: drop ALREADY_HAVE_ASCIIDOCTOR variable, 2026-09-02)
>
> But this is a third one (ci: use system asciidoctor)---it seems it was never
> picked up.

Ahh, that was originally 3 patch series.  I see where it went wrong.

Let's queue it on top.

Thanks.

Re: [PATCH] ci: fix missing Ruby dependency in "documentation" job

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> But these days I'd guess everybody is using v2.0.x (which seems to work
> fine) for local builds. We probably ought to do the same in CI. If we
> have to catch issues in one, I'd rather it be the one people are likely
> to actually use.
>
> It's possible that we could benefit from building with both in order to
> support the older version. But given its age I doubt it's worth it. We
> can still take bug fixes if somebody finds a problem, but we don't
> necessarily need to spend cycles building every commit with 1.5.8.

Yup, thanks for a dose of sanity.