Your message dated Tue, 28 Dec 2021 17:37:42 +0000
with message-id <[email protected]>
and subject line Bug#993681: fixed in sphinxcontrib-programoutput 0.16-2
has caused the Debian Bug report #993681,
regarding sphinxcontrib-programoutput: please make the build reproducible
to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact [email protected]
immediately.)
--
993681: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=993681
Debian Bug Tracking System
Contact [email protected] with problems
--- Begin Message ---
Source: sphinxcontrib-programoutput
Version: 0.16-1
Severity: normal
Tags: patch
User: [email protected]
Usertags: buildpath timezone username usrmerge
X-Debbugs-Cc: [email protected]
sphinxcontrib-programoutput builds non-reproducible documentation. The
documentation contains the current username, the absolute path to grep
(which can vary depending on merged-/usr status or whether a local
/usr/local/bin/grep exists), and the date on the grep executable (which
is presented differently depending on the timezone).
Additionally, a lot of the examples use `python`, which typically doesn't
exist in a build chroot, making them less useful as examples and
introducing the current build path via error messages.
The attached patch avoids these sources of non-reproducibility.
smcv
>From ef6355cb5d4e5376bdd5e24cd38198c0d83ca6ae Mon Sep 17 00:00:00 2001
From: Simon McVittie <[email protected]>
Date: Sat, 4 Sep 2021 18:36:14 +0100
Subject: [PATCH] Make the documentation build reproducibly
These patches avoid the username, the absolute path to grep and the
build path leaking into documentation and making it non-reproducible,
as well as making some examples in the documentation more useful.
---
...t-variable-less-likely-to-vary-betwe.patch | 38 +++++++
...ell-command-whose-output-is-less-lik.patch | 35 ++++++
...ython3-instead-of-python-in-examples.patch | 107 ++++++++++++++++++
debian/patches/series | 3 +
debian/rules | 4 +
5 files changed, 187 insertions(+)
create mode 100644 debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
create mode 100644 debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
create mode 100644 debian/patches/doc-Use-python3-instead-of-python-in-examples.patch
diff --git a/debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch b/debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
new file mode 100644
index 0000000..e4515cc
--- /dev/null
+++ b/debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
@@ -0,0 +1,38 @@
+From: Simon McVittie <[email protected]>
+Date: Sat, 4 Sep 2021 18:33:37 +0100
+Subject: doc: Use an environment variable less likely to vary between builds
+
+SHELL is less user-specific than USER, and can easily be forced to a
+known value for reproducible builds.
+
+Signed-off-by: Simon McVittie <[email protected]>
+---
+ doc/index.rst | 8 ++++----
+ 1 file changed, 4 insertions(+), 4 deletions(-)
+
+diff --git a/doc/index.rst b/doc/index.rst
+index 8175499..7bffe9c 100644
+--- a/doc/index.rst
++++ b/doc/index.rst
+@@ -114,17 +114,17 @@ Normally the command is splitted according to the POSIX shell syntax (see
+ :py:mod:`shlex`), and executed directly. Thus special shell features like
+ expansion of environment variables will not work::
+
+- .. command-output:: echo "$USER"
++ .. command-output:: echo "$SHELL"
+
+-.. command-output:: echo "$USER"
++.. command-output:: echo "$SHELL"
+
+ To enable these features, enable the ``shell`` option. With this option, the
+ command is literally passed to the system shell::
+
+- .. command-output:: echo "$USER"
++ .. command-output:: echo "$SHELL"
+ :shell:
+
+-.. command-output:: echo "$USER"
++.. command-output:: echo "$SHELL"
+ :shell:
+
+ Other shell features like process expansion consequently work, too::
diff --git a/debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch b/debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
new file mode 100644
index 0000000..9cef3e7
--- /dev/null
+++ b/debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
@@ -0,0 +1,35 @@
+From: Simon McVittie <[email protected]>
+Date: Sat, 4 Sep 2021 18:29:53 +0100
+Subject: doc: Use an example shell command whose output is less likely to
+ vary
+
+The path returned by $(which grep) might change depending on whether
+the system is merged-/usr or whether it has a local /usr/local/bin/grep,
+and the result of running ls can depend on factors such as the time zone.
+
+Using a different command here also helps to illustrate that shell
+syntax such as "&&" is accepted here, and using "command -v" avoids
+deprecation warnings from debianutils which(1).
+
+Signed-off-by: Simon McVittie <[email protected]>
+---
+ doc/index.rst | 4 ++--
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+
+diff --git a/doc/index.rst b/doc/index.rst
+index 6b5a0cc..8175499 100644
+--- a/doc/index.rst
++++ b/doc/index.rst
+@@ -129,10 +129,10 @@ command is literally passed to the system shell::
+
+ Other shell features like process expansion consequently work, too::
+
+- .. command-output:: ls -l $(which grep)
++ .. command-output:: test -x $(command -v grep) && echo yes
+ :shell:
+
+-.. command-output:: ls -l $(which grep)
++.. command-output:: test -x $(command -v grep) && echo yes
+ :shell:
+
+ Remember to use ``shell`` carefully to avoid unintented interpretation of shell
diff --git a/debian/patches/doc-Use-python3-instead-of-python-in-examples.patch b/debian/patches/doc-Use-python3-instead-of-python-in-examples.patch
new file mode 100644
index 0000000..d28f70b
--- /dev/null
+++ b/debian/patches/doc-Use-python3-instead-of-python-in-examples.patch
@@ -0,0 +1,107 @@
+From: Simon McVittie <[email protected]>
+Date: Sat, 4 Sep 2021 18:21:58 +0100
+Subject: doc: Use python3 instead of python in examples
+
+This makes the examples more illustrative, by running a command that
+actually exists. It also avoids embedding the full path to the build
+directory in the generated documentation, which is bad for reproducible
+builds.
+
+Signed-off-by: Simon McVittie <[email protected]>
+---
+ doc/index.rst | 26 +++++++++++++-------------
+ 1 file changed, 13 insertions(+), 13 deletions(-)
+
+diff --git a/doc/index.rst b/doc/index.rst
+index 8710bbe..6b5a0cc 100644
+--- a/doc/index.rst
++++ b/doc/index.rst
+@@ -35,13 +35,13 @@ Usage
+ To include the output of a command into your document, use the
+ :dir:`program-output` directive provided by this extension::
+
+- .. program-output:: python -V
++ .. program-output:: python3 -V
+
+-The whole output of ``python -V``, including any messages on standard error, is
++The whole output of ``python3 -V``, including any messages on standard error, is
+ inserted into the current document, formatted as literal text without any
+ syntax highlighting:
+
+-.. program-output:: python -V
++.. program-output:: python3 -V
+
+ You can omit the content of the standard error stream with the ``nostderr``
+ option.
+@@ -61,12 +61,12 @@ single ellipsis ``...`` is inserted.
+
+ If used with a single number, all lines after the specified line are omitted::
+
+- .. program-output:: python --help
++ .. program-output:: python3 --help
+ :ellipsis: 2
+
+ The above omits all lines after the second one:
+
+-.. program-output:: python --help
++.. program-output:: python3 --help
+ :ellipsis: 2
+
+ Negative numbers count from the last line backwards, thus replacing ``2`` with
+@@ -76,12 +76,12 @@ If used with two comma-separated line numbers, all lines in between the
+ specified lines are omitted. Again, a negative number counts from the last
+ line backwards::
+
+- .. program-output:: python --help
++ .. program-output:: python3 --help
+ :ellipsis: 2,-2
+
+ The above omits all lines except the first two and the last two lines:
+
+-.. program-output:: python --help
++.. program-output:: python3 --help
+ :ellipsis: 2,-2
+
+
+@@ -91,19 +91,19 @@ Mimicing shell input
+ You can mimic shell input with the :dir:`command-output` directive [#alias]_.
+ This directive inserts the command along with its output into the document::
+
+- .. command-output:: python -V
++ .. command-output:: python3 -V
+
+-.. command-output:: python -V
++.. command-output:: python3 -V
+
+ The appearance of this output can be configured with
+ :confval:`programoutput_prompt_template`. When used in conjunction with
+ ``ellipsis``, the command itself and any additional text is *never* omitted.
+ ``ellipsis`` always refers to the *immediate output* of the command::
+
+- .. command-output:: python --help
++ .. command-output:: python3 --help
+ :ellipsis: 2
+
+-.. command-output:: python --help
++.. command-output:: python3 --help
+ :ellipsis: 2
+
+
+@@ -150,7 +150,7 @@ indicate an error. In some cases however, it may be reasonable to demonstrate
+ failed programs. To avoid a (superfluous) warning in such a case, you can
+ specify the expected return code of a command with the ``returncode`` option::
+
+- .. command-output:: python -c 'import sys; sys.exit(1)'
++ .. command-output:: python3 -c 'import sys; sys.exit(1)'
+ :returncode: 1
+
+ The above command returns the exit code 1 (as given to :py:func:`sys.exit()`),
+@@ -235,7 +235,7 @@ This extension understands the following configuration options:
+ :dir:`command-output`. Defaults to ``$ {command}\n{output}`` which renders
+ as follows:
+
+- .. command-output:: python -V
++ .. command-output:: python3 -V
+
+ The following keys are provided to the format string:
+
diff --git a/debian/patches/series b/debian/patches/series
index 338f448..1c85ee6 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -1,3 +1,6 @@
remove-failing-tests-when-LANG-equal-C.patch
+doc-Use-python3-instead-of-python-in-examples.patch
+doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
+doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
#fix-tests-for-sphinx-1.8.patch
#use-py3-in-tests.patch
diff --git a/debian/rules b/debian/rules
index df341b6..9173080 100755
--- a/debian/rules
+++ b/debian/rules
@@ -3,6 +3,10 @@
UPSTREAM_GIT := https://github.com/NextThought/sphinxcontrib-programoutput
include /usr/share/openstack-pkg-tools/pkgos.make
+# Used in an example in generated documentation. Force it to a known value
+# to get reproducible builds
+export SHELL = /bin/sh
+
%:
dh $@ --buildsystem=python_distutils --with python3,sphinxdoc
--
2.33.0
--- End Message ---
--- Begin Message ---
Source: sphinxcontrib-programoutput
Source-Version: 0.16-2
Done: Thomas Goirand <[email protected]>
We believe that the bug you reported is fixed in the latest version of
sphinxcontrib-programoutput, 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 [email protected],
and the maintainer will reopen the bug report if appropriate.
Debian distribution maintenance software
pp.
Thomas Goirand <[email protected]> (supplier of updated
sphinxcontrib-programoutput 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 [email protected])
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Format: 1.8
Date: Tue, 28 Dec 2021 18:21:12 +0100
Source: sphinxcontrib-programoutput
Architecture: source
Version: 0.16-2
Distribution: unstable
Urgency: medium
Maintainer: Debian OpenStack <[email protected]>
Changed-By: Thomas Goirand <[email protected]>
Closes: 993681
Changes:
sphinxcontrib-programoutput (0.16-2) unstable; urgency=medium
.
* Apply patch to make doc reproducible. Thanks to Simon McVittie for the
patch (Closes: #993681).
Checksums-Sha1:
0e9388dce08dfbcd54508a2dca2131b030fd8c1b 2420
sphinxcontrib-programoutput_0.16-2.dsc
ee8877939cf2739e7fb72f43ca4f82415c040992 10220
sphinxcontrib-programoutput_0.16-2.debian.tar.xz
5f58b502f9d71e469a3314301b1642324a183015 8560
sphinxcontrib-programoutput_0.16-2_amd64.buildinfo
Checksums-Sha256:
2af516bc2f84b779fc3fe764f335de10539597d635648cff43c578dcca924050 2420
sphinxcontrib-programoutput_0.16-2.dsc
dbf3de5512b1d7f39a32073cfb6fc5b7d9caa9d1de39cfaf6afcd60dc6fa7ef5 10220
sphinxcontrib-programoutput_0.16-2.debian.tar.xz
5f1602529710377bfc5ce9084d65bcbd2c1c9ec3298ed11369d1c2592b1a2dca 8560
sphinxcontrib-programoutput_0.16-2_amd64.buildinfo
Files:
1741ea67ba6c552dc519167b28279c02 2420 python optional
sphinxcontrib-programoutput_0.16-2.dsc
fbfb1d3c56a0ed4ab1983c109be70525 10220 python optional
sphinxcontrib-programoutput_0.16-2.debian.tar.xz
195e9284095181dbb081affb331ea16f 8560 python optional
sphinxcontrib-programoutput_0.16-2_amd64.buildinfo
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCAAdFiEEoLGp81CJVhMOekJc1BatFaxrQ/4FAmHLSBIACgkQ1BatFaxr
Q/44lA/+J67MibGrYm2myDQevrV5D41P86UvUau37dGxlLa3p/58ZA0keW6QNmX6
1fk8Mrvwr+QCcTeYO2G1pPBQYILbpwsThV/BPbtvpF0dvL3chXWrcePHyui0412K
pX5irsUG9Bmzbco2Kxmql7wW60bcvX2EkSsEbx/bDLYvc9VW2+9gNaT+VntL0k1z
tBUlIuRHAD03suTEXtK1vZYEjr6MNVDLG+Mf33VWHi/zl8eFvXVeYtxEIbyC4aRi
Xk53mAw29fdnlUMwhDqxLEvCa6Wfwbh8ID4idxHMxhC86E7GKQP67GH8xHHSePRK
v2i57vnP9swlvDw7PgBsgRT1SQ4A6yIGm7MSuKKCf4WenYZIvJA2UoCLELTV1OJI
/slB8dO5zDLpFv2/ACovGTawe4dZD4rRm1QWiIZWw55SFAxucYqb6Ft6xI4OVmeG
CxOhILbasWRmhXjjWtdRVekXoHqQjE3QOOdw+ct8SUSUsHzbUAxgXqnej9PoxK7A
Wgi2memEicPUybczgjhnBX+RLZqL9Xo5QzLI2A+J/jJJTLquewRWU3eldqnORQON
p96kzwqtW4cD0ft8ovIk5e/YVhqd+1zKoJ4eLXE8QNQe5d2bk5rC2QFcDE7aWgyW
MMmEbGB3+8ixCW1vP9jEL8JpQq0BVe73su04GB3zFHNDYJ1xtAs=
=d5Dt
-----END PGP SIGNATURE-----
--- End Message ---
