The move of libjs-jquery, libjs-sphinxdoc and sphinx-rtd-theme-common
from Recommends to Depends has broken installation of this package on
stable.

Policy and dev-ref deliberately kept these in Recommends in order to
support this use case.  Indeed, my configuration management scripts for
my own machines are now failing :)

hi Sean,

thanks for the bug report!

Looping in the debhelper maintainer(s) as I have a question & thus
leaving the full context...:

(this happended when switching to debhelper-compat 14 in the last upload..._)

i'm not sure if this possible with compat=14 or whether I should revert
to what we did with dev-ref 14.15 using compat=13 ?

Holger Levsen:

Hi,

This is a likely a consequence of relationship substvars. Which ever
tool adds those dependencies (I do not know which it is, but likely
`sphinxdoc` since it is the only add-on sequence I noticed in devref)
will need to evaluate how to handle the case where these should not be
hard dependencies.

The discussion I had with Hefee in #1133692 might be interesting as
context here for the maintainer of the tool in question. It was another
case where a helper needed to tweak its behaviour in response to the
relationship substvar support in debhelper.

 From a devref maintainer PoV, you have to downgrade to compat 13 while
it is resolved (depending on how important this feature is). You can
also take the "substvar" rewrite solution from
https://lists.debian.org/debian-devel/2024/03/msg00030.html. I do not
recommend it, but it is an option.

Best regards,
Niels

Depends: ${misc:Depends}
Recommends: debian-policy,
 sensible-utils,
 ${sphinxdoc:Depends},


why is this turned into a depends?

& ayway, I've reverted the switch to debhelper 14 for now...

Hello,

Bug #1148587 in developers-reference reported by you has been fixed in the
Git repository and is awaiting an upload. You can see the commit
message below and you can check the diff of the fix at:

https://salsa.debian.org/debian/developers-reference/-/commit/9b10071d88a68f7bb5f0e10abca3a05b3d9afdc7
This reverts commit 2d9c30638952b3ea8a4ae0c014ad7af581819dcb.
------------------------------------------------------------------------

(this message was generated automatically)
-- 
Greetings

https://bugs.debian.org/1148587

debhelper compat level 14 automatically takes all substvars named like
foo:Depends (etc.) and adds them to Depends (etc.), without them needing
to be explicitly listed in d/control. See
debhelper-compat-upgrade-checklist(7) for full details.

To take something that is normally a Depends and downgrade it to a
Recommends, you'd need either a new feature in dh_sphinxdoc giving it an
option to generate a sphinxdoc:Recommends substvar instead (analogous to
the way that dpkg-shlibdeps -dRecommends generates shlibs:Recommends),
or to go back to compat level 13 (as you've done).

     smcv

ic. i still find this confusing as ${sphinxdoc:Depends} above is listed under Recommends:.

well, going back to compat level 13 is a workaround for now, but it will stop
being supported eventually...

We believe that the bug you reported is fixed in the latest version of
developers-reference, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 1148587@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Holger Levsen <holger@debian.org> (supplier of updated developers-reference package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)
Format: 1.8
Date: Sat, 26 Sep 2026 14:46:40 +0200
Source: developers-reference
Architecture: source
Version: 14.17
Distribution: unstable
Urgency: medium
Maintainer: Developers Reference Maintainers <debian-policy@lists.debian.org>
Changed-By: Holger Levsen <holger@debian.org>
Closes: 1148587
Changes:
 developers-reference (14.17) unstable; urgency=medium
 .
   * Revert "Switch to debhelper 14, moving libjs-jquery, libjs-sphinxdoc and
     sphinx-rtd-theme-common from recommends to depends." Closes: #1148587.
Checksums-Sha1:
 86abce394881f9fb0848444756ca6789409afcd5 2526 developers-reference_14.17.dsc
 6c019a87adccb6d10963129fd90bbc222747b8b3 584108 developers-reference_14.17.tar.xz
 43b2b9b495a3d2487821a25df94496772901eb96 8702 developers-reference_14.17_source.buildinfo
Checksums-Sha256:
 3d31b43c58b2f6761655537be83771120feb2c9dc041214f2eb640cd641505ae 2526 developers-reference_14.17.dsc
 86b5c3fa6fc06e811538b7fafd28b889941970bb2258d937e2caed76b11fb2c9 584108 developers-reference_14.17.tar.xz
 c307fe6268de18ee9445d8db1a4676f04040972a41704f10d0328c49061c8c61 8702 developers-reference_14.17_source.buildinfo
Files:
 7a57e469cf4a1d5cad6776a706272e94 2526 doc optional developers-reference_14.17.dsc
 7d1fb68ab84997f1eada27a0a2cf9a2a 584108 doc optional developers-reference_14.17.tar.xz
 186a3888a719db8ef1b3690b831946cb 8702 doc optional developers-reference_14.17_source.buildinfo
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEuL9UE3sJ01zwJv6dCRq4VgaaqhwFAmq3vv8ACgkQCRq4Vgaa
qhx4Hw//aAiLxMT/IT7ZqrPW7DRkf8xmQhHW5+KzJyz4HpnZxigPh2nFl3MEMp67
mrw/Nbcq6jbGD3fTWP+9oNzIAqf+Xy2zJZueABmxHJCeE374o+sNizwRQdPg5itA
HObznho2i+2DaGn6lM/bMqKF1j7aZ5TfWRJWHuJqzKtcaPYKZeVnsX5uHSDbTKTy
6R1le5GF7mwdAn9QTTgrgR5H00Cy8JFsZ6I33J3pfw0YIZti4CqL/DPxgdi49EZQ
hJL1br3Yfb3J6+6kq7a6v69sQJcjHY0fIf1nHNerU0PZRPzDITooX9yAR/6O78lg
913XxJ3HbEmtO5CidDGV7xbvMeAYTXHqNplxrWG1QLElIFL7xvL5yk3eBsSgaO/D
Ow9AB9DuFXr5joeJS1RPoKSYTMrcJ036vRQefGyf4L7tAPGmMCmRKV3JoCa/5H/c
OoeBGjWrz5imE2OB9j2XLfSNEbSlM0CjHX6GIkV+3Hc4kWrKI64fu4ISIbpnQ16S
st0R8FzZGrEx4f6Tj7jCye4FHcJCHNlaVw+8taiNi9bXD0ewbz3CMZA/dLbYkJnx
pFl1ae12B2ZFJgSC9u4PXhugQdjV1P4/oiu77OZIvl3sq/XUszqaj2/sAhnqbQeR
c9daqCPkLQgxnJTds6bHQ8YJewFHWSxK4LDTsotrBccNmRFeUok=
=K4BU
-----END PGP SIGNATURE-----