Copier Template: Improve Git hook performance.

Also,

* Copier Template: Refactor test commands to account for slow tests and
  doctests separately.

* Copier Template: Return success from Pytest when no matching tests are
  found. (Useful for when there are no slow tests to run.)

* Documentation: validation: Reflect test commands refactor.

* Documentation: releases: Improve procedure for release candidates.

* Copier Template: Claude Commands: release-final: Improve procedure for
  releases; bring it inline with manual releases procedure.

Author: emcd

.auxiliary/configuration/pre-commit.yaml

@@ -49,6 +49,14 @@ repos:
 - repo: local
   hooks:
 
+  - id: hatch-pytest
+    name: 'Test Code Units (Python)'
+    fail_fast: true
+    language: system
+    always_run: true
+    pass_filenames: false
+    entry: 'hatch --env develop run pytest'
+
   - id: hatch-pyright
     name: 'Lint: Pyright'
     stages: [ 'pre-push' ]

documentation/common/releases.rst

@@ -32,9 +32,7 @@ Pre-Release Quality Check
 Run local quality assurance before any release process::
 
     git status && git pull origin master
-    hatch --env develop run linters
-    hatch --env develop run testers
-    hatch --env develop run docsgen
+    hatch --env develop run make-all
 
 Also, ensure that at least one news fragment exists under
 ``.auxiliary/data/towncrier``.
@@ -70,8 +68,9 @@ Initial Release Candidate
 
         git checkout master
         hatch version minor,alpha
-        git commit -am "Start development for v$(hatch version | sed 's/a[0-9]*$//')."
-        git tag -m "Start development for v$(hatch version | sed 's/a[0-9]*$//')." i$(hatch version | sed 's/a[0-9]*$//')
+        next_release="$(hatch version | sed 's/a[0-9]*$//')"
+        git commit -am "Start of development for release ${next_release}."
+        git tag -m "Start of development for release ${next_release}." "i${next_release}"
         git push origin master --tags
 
 Final Release

documentation/common/validation.rst

@@ -34,14 +34,13 @@ Run validation commands using ``hatch --env develop run <command>``.
   Runs code quality checks including Ruff linting, Pyright type checking, and
   Rust linting (if applicable). Must pass with no errors.
 
+**pytest**
+  Runs quick tests. Useful for quick validation during development.
+
 **testers**
   Runs the full test suite with coverage reporting. Generates HTML and XML
   coverage reports in ``.auxiliary/artifacts/coverage-pytest/``.
 
-**testers-no-reports**
-  Runs tests without generating coverage reports. Useful for quick validation
-  during development.
-
 **packagers**
   Builds distribution packages using Hatch. Also builds standalone executables
   via PyInstaller (if enabled).
@@ -58,11 +57,11 @@ Run validation commands using ``hatch --env develop run <command>``.
 Workflow
 ===============================================================================
 
-1. **During Development**: Use ``testers-no-reports`` for quick feedback.
+1. **During Development**: Use ``pytest`` for quick feedback.
 2. **Before Committing**: Run ``linters`` to catch some bugs, code smells, and
    type issues.
 3. **Before Pull Requests**: Run ``make-all`` to ensure all validation passes.
 
 All validation commands must pass without errors before contributions can be
 accepted. If you installed the Git pre-commit and pre-push hooks for the
-project, then they will perform these validations for you.
+project, then they will perform most of these validations for you.

template/.auxiliary/configuration/claude/commands/release-final.md

@@ -166,7 +166,7 @@ Set up next development version:
 ```bash
 hatch version minor,alpha
 git commit -am "Start of development for release $(hatch version | sed 's/a[0-9]*$//')."
-git tag -m "Start of development for $(hatch version | sed 's/a[0-9]*$//')." "i$(hatch version | sed 's/a[0-9]*$//')"
+git tag -m "Start of development for release $(hatch version | sed 's/a[0-9]*$//')." "i$(hatch version | sed 's/a[0-9]*$//')"
 git push origin master --tags
 ```
 

template/.auxiliary/configuration/pre-commit.yaml

@@ -49,6 +49,14 @@ repos:
 - repo: local
   hooks:
 
+  - id: hatch-pytest
+    name: 'Test Code Units (Python)'
+    fail_fast: true
+    language: system
+    always_run: true
+    pass_filenames: false
+    entry: 'hatch --env develop run pytest'
+
   - id: hatch-pyright
     name: 'Lint: Pyright'
     stages: [ 'pre-push' ]
@@ -83,4 +91,4 @@ repos:
     language: system
     always_run: true
     pass_filenames: false
-    entry: 'hatch --env develop run packagers'
+    entry: 'hatch build'

template/.gitignore

@@ -9,3 +9,4 @@ CONVENTIONS.md
 GEMINI.md
 __pycache__/
 bugs/
+build/

template/pyproject.toml.jinja

@@ -77,7 +77,7 @@ gha-runners = [
 ]
 [tool.coverage.run]
 branch = true
-command_line = '-m pytest' # TODO? '--fail-under'
+command_line = '-m pytest'
 data_file = '.auxiliary/caches/pytest/coverage.sqlite3'
 parallel = true
 source = [ 'sources' ]
@@ -165,9 +165,9 @@ HYPOTHESIS_STORAGE_DIRECTORY = '.auxiliary/caches/hypothesis'
 [tool.hatch.envs.develop.scripts]
 docsgen = [
   """sphinx-build -E -b linkcheck -d .auxiliary/caches/sphinx \
-     documentation .auxiliary/artifacts/sphinx-linkcheck""",
+      documentation .auxiliary/artifacts/sphinx-linkcheck""",
   """sphinx-build -a -d .auxiliary/caches/sphinx \
-     documentation .auxiliary/artifacts/sphinx-html""",
+      documentation .auxiliary/artifacts/sphinx-html""",
 ]
 linters = [
   """ruff check --quiet sources documentation tests""",
@@ -176,7 +176,7 @@ linters = [
   # TODO: Use '-C' flag, which is only on nightly, as of 2024-12-11.
   """cargo check --manifest-path sources/{{ crate_name }}/Cargo.toml""",
   """cargo clippy --manifest-path sources/{{ crate_name }}/Cargo.toml \
-     -- --deny warnings --warn clippy::pedantic""",
+      -- --deny warnings --warn clippy::pedantic""",
   # TODO: cargo deny # Not installed with Cargo by default.
   {%- endif %}
   # --- END: Injected by Copier ---
@@ -193,14 +193,19 @@ packagers = [
   {%- endif %}
   # --- END: Injected by Copier ---
 ]
+testers-documentation = [
+  """coverage run -m sphinx.cmd.build \
+      -E -b doctest -d .auxiliary/caches/sphinx \
+      documentation .auxiliary/artifacts/sphinx-doctest""",
+]
+testers-serotine = [ """coverage run -m pytest -m 'slow'"""  ]
 testers-no-reports = [
-  'coverage erase',
   'coverage run',
-  """coverage run -m sphinx.cmd.build \
-     -E -b doctest -d .auxiliary/caches/sphinx \
-     documentation .auxiliary/artifacts/sphinx-doctest""",
+  'testers-documentation',
+  'testers-serotine',
 ]
 testers = [
+  'coverage erase',
   'testers-no-reports',
   'coverage combine',
   'coverage report --skip-covered',
@@ -287,11 +292,14 @@ stubPath = 'sources/{{ package_name }}/_typedecls'
 # Note: Cannot run doctests from Pytest, because Pytest tries to update '_'
 #       attribute on protected modules. Instead, we use Sphinx to run doctests.
 minversion = '8.1'
-addopts = '--capture=no --exitfirst -rfE'
+addopts = """--capture=no --exitfirst -rfE -m 'not slow'""" # TODO? '--fail-under'
 testpaths = [ 'tests' ]
 python_files = [ 'test_*.py' ]
 python_functions = [ 'test_[0-9][0-9][0-9]_*' ]
 cache_dir = '.auxiliary/caches/pytest'
+markers = [
+    "slow: long-running tests",
+]
 
 [tool.ruff]
 #builtins = [ 'ic' ]

template/tests/test_000_{{ package_name }}/conftest.py

@@ -0,0 +1,3 @@
+def pytest_sessionfinish( session, exitstatus ):
+    if exitstatus == 5:  # pytest exit code for "no tests collected"
+        session.exitstatus = 0