Make more user facing

Author: spoorcc

AGENTS.md

@@ -23,6 +23,9 @@ behave features/
 # Single feature file
 behave features/git-fetch.feature
 
+# Feature tests for a specific command (e.g. update, check, diff, report)
+behave features/ --tags=update
+
 # Full test run with coverage (as CI does it)
 pytest --cov=dfetch tests/
 coverage run --source=dfetch --append -m behave features
@@ -87,6 +90,7 @@ Implement the abstract interfaces in `dfetch/project/subproject.py` and `dfetch/
 
 - **Unit tests** live in `tests/` and use `pytest`. Test files mirror module names (e.g., `tests/test_manifest.py`).
 - **BDD feature tests** live in `features/` and use `behave`. Step definitions are in `features/steps/`. Feature files describe end-to-end workflows.
+- Feature files are tagged with the command they exercise (e.g. `@update`, `@check`). If your change affects a command, run its feature tests using the command tag: `behave features/ --tags=<command>`.
 - Docstrings in test functions follow Google style as a convention (CI runs `pydocstyle dfetch` and does not check `tests/`, so this is not enforced automatically).
 
 ## Code quality rules

doc/_ext/scenario_directive.py

@@ -1,5 +1,5 @@
 """
-Custom Sphinx directive for including Gherkin scenarios from feature files.
+Custom Sphinx directive for including feature examples from feature files.
 
 Usage in conf.py:
 
@@ -14,12 +14,12 @@
 
     .. scenario-include:: ../features/fetch-git-repo.feature
        :scenario:
-          Scenario Title 1
-          Scenario Title 2
+          Example Title 1
+          Example Title 2
 
-If ``:scenario:`` is omitted, all scenarios in the feature file are included.
+If ``:scenario:`` is omitted, all examples in the feature file are included.
 
-**PDF / LaTeX builds** automatically move scenarios to an appendix grouped by
+**PDF / LaTeX builds** automatically move examples to an appendix grouped by
 the first non-excluded behave tag found on the feature file.  The directive's
 original location receives a cross-reference to the appendix entry instead.
 
@@ -144,9 +144,9 @@ def _tag_section_title(tag: str) -> str:
 
 
 class ScenarioIncludeDirective(Directive):
-    """Include Gherkin scenarios from a feature file.
+    """Include feature examples from a feature file.
 
-    In PDF/LaTeX builds the scenarios are moved to a dedicated appendix and
+    In PDF/LaTeX builds the examples are moved to a dedicated appendix and
     replaced inline by a cross-reference, unless ``:inline:`` is given.
     """
 
@@ -295,9 +295,9 @@ def _render_pdf(
         ref_node["label"] = label
         ref_node["reftitle"] = title
         para = nodes.paragraph()
-        para += nodes.emphasis(text="Scenarios: see ")
+        para += nodes.Text("See the example \u201c")
         para += ref_node
-        para += nodes.emphasis(text=" in the appendix.")
+        para += nodes.Text("\u201d in the Appendix.")
         return [para]
 
     # ------------------------------------------------------------------
@@ -327,14 +327,14 @@ def run(self) -> List[nodes.Node]:
 
 
 class ScenarioAppendixDirective(Directive):
-    """Render the appendix of all PDF-deferred scenarios.
+    """Render the appendix of all PDF-deferred feature examples.
 
     Place this directive once in the document (typically in an appendix
     page).  During the write phase it is replaced by sections grouped by
     the first non-excluded tag, sorted alphabetically, containing the full
     content of each referenced feature file.
 
-    In HTML builds scenarios appear inline in the main text, so this
+    In HTML builds examples appear inline in the main text, so this
     directive emits an explanatory note instead.
     """
 
@@ -348,9 +348,9 @@ def run(self) -> List[nodes.Node]:
             note = nodes.note()
             para = nodes.paragraph()
             para += nodes.Text(
-                "In the HTML edition, feature scenarios appear as expandable "
-                "examples directly within each guide section. "
-                "In the PDF edition they are collected here, grouped by tag."
+                "In the HTML edition, feature examples appear as expandable "
+                "blocks directly within each guide section. "
+                "In the PDF edition they are collected here, grouped by command."
             )
             note += para
             return [note]

doc/appendix/scenarios.rst

@@ -1,11 +1,14 @@
 .. _scenario-appendix:
 
-Appendix: Feature scenarios
+Appendix: Feature Examples
 ============================
 
-This appendix collects all the Gherkin feature scenarios that illustrate
-dfetch's behaviour. In the HTML documentation each scenario appears inline,
-folded inside an expandable *Example* block. In the PDF edition the scenarios
-are moved here, grouped alphabetically by tag.
+This appendix collects all the feature test examples that demonstrate dfetch's
+behaviour. Each example is an actual test that runs as part of dfetch's test
+suite, showing exactly how dfetch behaves in a given situation.
+
+In the HTML documentation each example appears inline, folded inside an
+expandable block directly within the relevant guide section. In the PDF
+edition they are collected here, grouped by command.
 
 .. scenario-appendix::

doc/howto/contributing.rst

@@ -83,19 +83,27 @@ Feature tests
 ~~~~~~~~~~~~~
 Feature tests are used for higher-level integration testing of functionality.
 For this `behave <https://behave.readthedocs.io/en/latest/>`_ is used as testing framework.
-Features are specified in *Gherkin* in so-called feature files in the ``features`` folder.
-The sentences in the feature files, map to steps in the ``features/steps`` folder.
+Feature files in the ``features`` folder contain plain-language examples that
+demonstrate dfetch's behaviour. The sentences in the feature files map to step
+definitions in the ``features/steps`` folder.
 
-Test can be run directly from the command-line
+Tests can be run directly from the command-line:
 
 .. code-block:: bash
 
     behave features
 
+Feature files are tagged with the command they exercise (e.g. ``@update``,
+``@check``). You can run just the examples for a specific command using its tag:
+
+.. code-block:: bash
+
+    behave features --tags=update
+
 Alternatively in VSCode run the ``Run all feature tests`` task from the command palette.
 
 To debug these tests, mark the ``Feature:`` or ``Scenario:`` to debug with the ``@wip`` tag
-and add run the ``Feature tests (wip)`` debug configuration in VSCode.
+and run the ``Feature tests (wip)`` debug configuration in VSCode.
 
 
 Creating documentation