Update upstream source from tag 'upstream/0.1.5'

Update to upstream version '0.1.5'
with Debian dir 0ccf7c283ba9d75299b554ccc2a4677d80f5efba

15 files changed, 118 insertions, 28 deletions

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 8a5d014..4a82e86 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -3,6 +3,11 @@
 
 version: 2
 
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3.12"
+
 mkdocs:
     configuration: mkdocs.yml
 
diff --git a/PKG-INFO b/PKG-INFO
index c0cde73..f12d7b4 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: test_stages
-Version: 0.1.4
+Version: 0.1.5
 Summary: Group Tox, Nox, etc environments into stages, run them in parallel
 Project-URL: Homepage, https://devel.ringlet.net/devel/test-stages
 Project-URL: Changes, https://devel.ringlet.net/devel/test-stages/changes/
diff --git a/config/ruff-base/pyproject.toml b/config/ruff-base/pyproject.toml
index daf1352..bd952ab 100644
--- a/config/ruff-base/pyproject.toml
+++ b/config/ruff-base/pyproject.toml
@@ -30,7 +30,7 @@ single-line-exclusions = ["collections.abc", "typing"]
 
 [tool.ruff.per-file-ignores]
 # The self-test tool uses subprocess responsibly.
-"src/selftest/__main__.py" = ["S603", "S607"]
+"src/selftest/__main__.py" = ["S404", "S603", "S607"]
 
 # mypy needs a couple of assertions, and some of them will be a bit unwieldy if
 # broken down into multiple statements.
@@ -38,4 +38,4 @@ single-line-exclusions = ["collections.abc", "typing"]
 
 # This is a unit test suite, it can output diagnostic messages.
 # Also, we try to use subprocess responsibly.
-"unit_tests/**.py" = ["S101", "S603", "S607", "T201"]
+"unit_tests/**.py" = ["S101", "S404", "S603", "S607", "T201"]
diff --git a/docs/changes.md b/docs/changes.md
index 5a25764..b2867e4 100644
--- a/docs/changes.md
+++ b/docs/changes.md
@@ -7,11 +7,44 @@ SPDX-License-Identifier: BSD-2-Clause
 
 All notable changes to the test-stages project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.5] - 2024-01-19
+
+### Fixes
+
+- documentation:
+    - add the "build" section to the ReadTheDocs configuration
+    - refer to version 1.1.0 of the "Keep a Changelog" specification in
+      the changelog file
+- selftest:
+    - validate the list of archive files before passing it to
+      `TarFile.extractall()`
+
+### Additions
+
+- documentation:
+    - add a "Download" page linking to the various files at the Ringlet website
+
+### Other changes
+
+- switch from `black` to `ruff` for source code formatting
+- documentation:
+    - use `mkdocstrings` 0.23 and `mkdocstrings-python` 1.x with no changes
+- testing framework:
+    - also run the "reuse" test in the first Tox stage
+    - also build the documentation in the second Tox stage
+    - Ruff:
+        - use Ruff 0.1.13
+        - disable another subprocess-related check (`S404`)
+        - let Ruff also validate the docstrings
+    - mypy:
+        - do not explicitly install `tomli`, it is brought in as
+          a runtime dependency
+
 ## [0.1.4] - 2023-10-19
 
 ### Fixes
@@ -182,7 +215,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [ringlet-test-stages]: https://devel.ringlet.net/devel/test-stages/ "The Ringlet test-stages homepage"
 [tool-mkdocs]: https://www.mkdocs.org/ "Project documentation with Markdown"
 
-[Unreleased]: https://gitlab.com/ppentchev/test-stages/-/compare/release%2F0.1.4...main
+[Unreleased]: https://gitlab.com/ppentchev/test-stages/-/compare/release%2F0.1.5...main
+[0.1.5]: https://gitlab.com/ppentchev/test-stages/-/compare/release%2F0.1.4...release%2F0.1.5
 [0.1.4]: https://gitlab.com/ppentchev/test-stages/-/compare/release%2F0.1.3...release%2F0.1.4
 [0.1.3]: https://gitlab.com/ppentchev/test-stages/-/compare/release%2F0.1.2...release%2F0.1.3
 [0.1.2]: https://gitlab.com/ppentchev/test-stages/-/compare/release%2F0.1.1...release%2F0.1.2
diff --git a/docs/download.md b/docs/download.md
new file mode 100644
index 0000000..8e50175
--- /dev/null
+++ b/docs/download.md
@@ -0,0 +1,35 @@
+<!--
+SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
+# Download
+
+These are the released versions of [test-stages](index.md) available for download.
+
+## [0.1.5] - 2024-01-19
+
+### Source tarball
+
+- [test_stages-0.1.5.tar.gz](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.5.tar.gz)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.5.tar.gz.asc))
+
+### Python wheel
+
+- [test_stages-0.1.5-py3-none-any.whl](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.5-py3-none-any.whl)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.5-py3-none-any.whl.asc))
+
+## [0.1.4] - 2023-12-19
+
+### Source tarball
+
+- [test_stages-0.1.4.tar.gz](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.4.tar.gz)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.4.tar.gz.asc))
+
+### Python wheel
+
+- [test_stages-0.1.4-py3-none-any.whl](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.4-py3-none-any.whl)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/test-stages/test_stages-0.1.4-py3-none-any.whl.asc))
+
+[0.1.5]: https://gitlab.com/ppentchev/test-stages/-/tags/release%2F0.1.5
+[0.1.4]: https://gitlab.com/ppentchev/test-stages/-/tags/release%2F0.1.4
diff --git a/mkdocs.yml b/mkdocs.yml
index 2bef9e8..6f1d918 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -28,6 +28,7 @@ site_url: https://devel.ringlet.net/devel/test-stages/
 site_dir: site/docs
 nav:
   - 'index.md'
+  - 'Download': 'download.md'
   - 'Changelog': 'changes.md'
   - 'Command-line tools': 'cmd/index.md'
   - 'The tox-stages tool': 'cmd/tox-stages.md'
diff --git a/pyproject.toml b/pyproject.toml
index a1aa2cb..b3e5111 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -69,10 +69,6 @@ files = ["requirements/install.txt"]
 [tool.hatch.version]
 path = "src/test_stages/__init__.py"
 
-[tool.black]
-target-version = ["py38", "py39", "py310", "py311", "py312"]
-line-length = 100
-
 [tool.mypy]
 strict = true
 
diff --git a/requirements/black.txt b/requirements/black.txt
deleted file mode 100644
index e64a1a5..0000000
--- a/requirements/black.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
-# SPDX-License-Identifier: BSD-2-Clause
-
-black >= 23.7, < 24
diff --git a/requirements/docs.txt b/requirements/docs.txt
index d9ca115..e961640 100644
--- a/requirements/docs.txt
+++ b/requirements/docs.txt
@@ -3,5 +3,5 @@
 
 mkdocs >= 1.4.2, < 2
 mkdocs-material >= 9.1.2, < 10
-mkdocstrings >= 0.21.2, < 0.22
-mkdocstrings-python >= 0.10.1, < 0.11
+mkdocstrings >= 0.23, < 0.24
+mkdocstrings-python >= 1, < 2
diff --git a/requirements/ruff.txt b/requirements/ruff.txt
index 4d07939..4639591 100644
--- a/requirements/ruff.txt
+++ b/requirements/ruff.txt
@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
 # SPDX-License-Identifier: BSD-2-Clause
 
-ruff == 0.1.0
+ruff == 0.1.13
diff --git a/src/selftest/__main__.py b/src/selftest/__main__.py
index 66dc1c0..f16a433 100644
--- a/src/selftest/__main__.py
+++ b/src/selftest/__main__.py
@@ -60,6 +60,30 @@ def build_sdist(srcdir: pathlib.Path, tempd: pathlib.Path) -> pathlib.Path:
         return sdist
 
 
+def safe_extract_all(star: tarfile.TarFile, topdir: pathlib.Path) -> None:
+    """Validate the member names in the archive and extract them all."""
+    members: Final = star.getmembers()
+    paths: Final = [pathlib.Path(member.name) for member in members]
+    if not paths:
+        sys.exit("Expected at least one member in the source archive")
+    if paths[0].is_absolute():
+        sys.exit(f"Did not expect an absolute path {paths[0]} in the source archive")
+
+    base_path: Final = paths[0].parts[0]
+    bad_paths: Final = [path for path in paths if path.parts[0] != base_path]
+    if bad_paths:
+        sys.exit(
+            f"Bad paths in the source archive, expected all of them to "
+            f"start with {base_path}: {bad_paths}"
+        )
+
+    bad_dirs: Final = [path for path in paths if ".." in path.parts]
+    if bad_dirs:
+        sys.exit(f"Bad paths in the source archive, none of them should contain '..': {bad_paths}")
+
+    star.extractall(topdir, members=members)  # noqa: S202
+
+
 def extract_sdist(sdist: pathlib.Path, tempd: pathlib.Path) -> pathlib.Path:
     """Extract the sdist tarball."""
     if not sdist.name.endswith(".tar.gz"):
@@ -69,7 +93,7 @@ def extract_sdist(sdist: pathlib.Path, tempd: pathlib.Path) -> pathlib.Path:
     topdir.mkdir(mode=0o755)
 
     with tarfile.open(sdist, mode="r") as star:
-        star.extractall(topdir)
+        safe_extract_all(star, topdir)
         entries: Final = sorted(path for path in topdir.iterdir())
         if len(entries) != 1:
             sys.exit(f"Expected {sdist} to contain a single directory, got {entries!r}")
diff --git a/src/test_stages/__init__.py b/src/test_stages/__init__.py
index cebc7fc..9a4543d 100644
--- a/src/test_stages/__init__.py
+++ b/src/test_stages/__init__.py
@@ -2,4 +2,4 @@
 # SPDX-License-Identifier: BSD-2-Clause
 """Run `tox` on several groups of environments, stopping on errors."""
 
-VERSION = "0.1.4"
+VERSION = "0.1.5"
diff --git a/src/test_stages/tox_stages/__main__.py b/src/test_stages/tox_stages/__main__.py
index 6843954..ec53985 100644
--- a/src/test_stages/tox_stages/__main__.py
+++ b/src/test_stages/tox_stages/__main__.py
@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 import dataclasses
-import subprocess
+import subprocess  # noqa: S404
 import sys
 from typing import TYPE_CHECKING
 
diff --git a/src/tox_trivtags/parse.py b/src/tox_trivtags/parse.py
index 108ab85..66399c2 100644
--- a/src/tox_trivtags/parse.py
+++ b/src/tox_trivtags/parse.py
@@ -10,7 +10,7 @@ import ast
 import configparser
 import itertools
 import pathlib
-import subprocess
+import subprocess  # noqa: S404
 import sys
 from typing import Final, NamedTuple
 
diff --git a/tox.ini b/tox.ini
index 03d92ad..31052c4 100644
--- a/tox.ini
+++ b/tox.ini
@@ -12,6 +12,7 @@ envlist =
   unit-tests-tox-3
   unit-tests-tox-4
   selftest
+  docs
 isolated_build = True
 
 [defs]
@@ -41,11 +42,10 @@ tags =
   check
   quick
 deps =
-  -r requirements/black.txt
   -r requirements/ruff.txt
 commands =
-  ruff check --config config/ruff-base/pyproject.toml --select=I --diff -- {[defs]pyfiles}
-  black --check {[defs]pyfiles}
+  ruff check --config config/ruff-base/pyproject.toml --select=D,I --diff -- {[defs]pyfiles}
+  ruff format --check --config config/ruff-base/pyproject.toml --diff -- {[defs]pyfiles}
 
 [testenv:reformat]
 skip_install = True
@@ -53,11 +53,10 @@ tags =
   format
   manual
 deps =
-  -r requirements/black.txt
   -r requirements/ruff.txt
 commands =
-  ruff check --config config/ruff-base/pyproject.toml --select=I --fix -- {[defs]pyfiles}
-  black {[defs]pyfiles}
+  ruff check --config config/ruff-base/pyproject.toml --select=D,I --fix -- {[defs]pyfiles}
+  ruff format --config config/ruff-base/pyproject.toml -- {[defs]pyfiles}
 
 [testenv:mypy]
 skip_install = True
@@ -68,7 +67,6 @@ deps =
   -r requirements/selftest.txt
   -r requirements/test.txt
   mypy >= 1, < 2
-  tomli >= 2, < 3; python_version < '3.11'
 
   # There seems to be some misunderstanding between mypy 1.4.1 and click 8.1.4
   click != 8.1.4
@@ -148,6 +146,7 @@ commands =
 skip_install = True
 tags =
   check
+  quick
 deps =
   reuse >= 2, < 3
 allowlist_externals =
@@ -158,8 +157,8 @@ commands =
 [testenv:docs]
 skip_install = True
 tags =
+  check
   docs
-  manual
 deps =
   -r requirements/docs.txt
 commands =