Doc update + fix format-patch

[spoorcc]

Update documentation

Summary by CodeRabbit

• New Features

  • Improved patch formatting: patches are now converted to the appropriate VCS patch type and prefixed correctly for mixed-VCS projects.

• Bug Fixes

  • Fixed inaccurate module documentation about backup behavior.

• Tests

  • Added scenarios covering Git-in-SVN and SVN-in-Git patch formatting; updated tests to validate parsing/serialization flow.

• Documentation

  • Updated asciicast transcripts, scenario rendering to use collapsible HTML details, and manifest examples/versions.

• Chores

  • Adjusted docs dependencies/configuration.

[coderabbitai]

Warning

Rate limit exceeded

@ben-edna has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 10 minutes and 44 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

Refactors patch formatting to operate on parsed PatchSet objects: adds parse/convert/dump utilities, updates add_prefix_to_patch to accept/return PatchSet, and changes format_patch to determine target patch type from subproject, convert, prefix, and serialize the patch before writing.

Changes

Cohort / File(s)	Summary
Core patch utilities dfetch/vcs/patch.py	Added parse_patch() and convert_patch_to(); changed add_prefix_to_patch() to accept and return patch_ng.PatchSet; introduced _rewrite_path() and header/path rewriting logic; added dump_patch (serialization).
Format patch command dfetch/commands/format_patch.py	Added _determine_target_patch_type(subproject); changed flow to parse_patch() → convert_patch_to(target_type) → add_prefix_to_patch() → dump_patch(); updated imports to include patch_ng, parse/convert/dump utilities and GitSubProject/SvnSubProject/SubProject.
Tests tests/test_patch.py	Updated to parse original patch into a PatchSet and verify output by dumping serialized prefixed patch; adjusts to new add_prefix_to_patch() signature.
Feature tests features/format-patch-in-git.feature, features/format-patch-in-svn.feature	Added scenarios validating VCS-aware patch formatting (SVN-in-Git and Git-in-SVN cases).
SVN revision bumps features/check-svn-repo.feature, features/freeze-projects.feature, features/import-from-svn.feature, features/fetch-svn-repo.feature	Updated expected SVN revision numbers (172 → 176) in manifests and assertions.
Gherkin step alias features/steps/git_steps.py	Added an alias step accepting phrasing with "git-repo" that maps to the existing manifest setup step.
Docs / casts doc/asciicasts/format-patch.cast, doc/asciicasts/update-patch.cast	Regenerated asciicast transcripts and metadata (shell, timestamps, dimensions) and updated demo README URLs and paths.
Docs rendering change doc/_ext/scenario_directive.py, doc/conf.py, pyproject.toml	Replaced Sphinx details directive with raw HTML <details> blocks; removed sphinxcontrib-details-directive extension and dependency; adjusted docs dependencies.
Minor docs dfetch/commands/update_patch.py, dfetch/commands/diff.py	Small docstring/help-text edits (removed outdated sentence; reformatted help reference).

Sequence Diagram

sequenceDiagram
participant FC as format_patch command
participant P as dfetch.vcs.patch utilities
participant SP as SubProject type
FC->>P: parse_patch(file_path)
P-->>FC: PatchSet
FC->>SP: _determine_target_patch_type(subproject)
SP-->>FC: target_type (GIT / SVN / PLAIN)
FC->>P: convert_patch_to(PatchSet, target_type)
P-->>FC: converted PatchSet
FC->>P: add_prefix_to_patch(PatchSet, prefix)
P-->>FC: prefixed PatchSet
FC->>P: dump_patch(PatchSet)
P-->>FC: serialized patch text
FC->>FC: write to output file

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Format patch command #976: Overlaps changes to format_patch.py and dfetch/vcs/patch.py—similar parsing/conversion flow updates.
• New files not part of dfetch diff generated patch #888: Adds/adjusts patch parsing and serialization helpers used by the new flow.
• Refactor projects #984: Exposes/centralizes SubProject/GitSubProject/SvnSubProject types relied on for target-type determination.

Suggested labels

bug, enhancement

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Doc update + fix format-patch' is somewhat vague and generic. While it mentions 'Doc update' and 'format-patch', it doesn't clearly specify what the actual changes are. The changeset includes significant code refactoring of the patch processing flow, changes to patch utilities, test updates, and feature additions beyond just documentation updates. The title obscures the main technical changes.	Consider a more specific title that captures the primary changes, such as 'Refactor patch processing with type conversion and path validation' or similar, to better reflect the substantial code changes alongside documentation updates.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 81.82% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch doc-update

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@dfetch/vcs/patch.py`:
- Around line 310-313: The header construction needs to special-case /dev/null
to avoid producing double slashes; update the loop that sets file.header for
items in patch.items so that when file.source == b"/dev/null" you do not prefix
it with b"a/" (and likewise when file.target == b"/dev/null" you do not prefix
it with b"b/"), building the header from chosen left/right parts (e.g., left =
file.source if file.source == b"/dev/null" else b"a/" + file.source; right =
file.target if file.target == b"/dev/null" else b"b/" + file.target) and then
set file.header = [b"diff --git " + left + b" " + right + b"\n"].
- Around line 304-321: Change the two separate if branches in convert_patch_to
to an if/elif (check patch_ng.GIT then elif patch_ng.SVN) so the GIT and SVN
handling are explicit and mutually exclusive, and after attempting conversion
validate the required_type: if it is not one of patch_ng.GIT or patch_ng.SVN
raise a clear error (e.g., ValueError) instead of silently setting patch.type;
ensure you still update each file.header and file.type inside the respective
branch and only set patch.type = required_type when a known conversion was
performed.

🧹 Nitpick comments (2)

tests/test_patch.py (1)

365-366: Minor type mismatch: parse_patch expects str but receives pathlib.Path.

original_patch_file is a pathlib.Path (from tmp_path / "original.patch"), but parse_patch(file_path: str) declares str. This works at runtime since patch_ng.fromfile accepts path-like objects, but it's inconsistent with the type annotation. Consider either updating the annotation in parse_patch to accept str | pathlib.Path, or wrapping with str(original_patch_file) here.

Option A: Fix at the call site

- parsed_patch = parse_patch(original_patch_file)+ parsed_patch = parse_patch(str(original_patch_file))

dfetch/commands/format_patch.py (1)

153-162: _determine_target_patch_type — remove redundant str() conversion.

All three constants (patch_ng.GIT, patch_ng.SVN, patch_ng.PLAIN) exist and are used consistently throughout the codebase. The isinstance-based dispatch is clean and the function is appropriately module-private.

However, the str() cast on line 162 is redundant. These constants are already strings—the function signature declares a -> str return type, and in convert_patch_to (line 306), required_type is compared directly to patch.type with ==, which works only because both are strings. Remove the str() wrapper for clarity: return required_type.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@pyproject.toml`:
- Line 100: The inline comment next to the dependency string 'setuptools;
python_version >= "3.12"' is stale because sphinxcontrib.details.directive is
being removed; either remove this setuptools marker from the docs extras if
nothing else requires pkg_resources, or update the comment to name the actual
consumer that needs setuptools (e.g., the specific Sphinx extension importing
pkg_resources). Locate the dependency string 'setuptools; python_version >=
"3.12"' in the pyproject.toml extras section and either delete the comment or
replace it with an accurate explanation of why setuptools is present.

🧹 Nitpick comments (2)

doc/_ext/scenario_directive.py (1)

81-96: Approach looks good — raw HTML replaces the removed sphinxcontrib-details-directive.

The sequential .. raw:: html blocks wrapping the literalinclude will produce a valid collapsible <details> element in the final output. One minor concern: scenario_title on line 84 is interpolated directly into raw HTML without escaping. If any Gherkin scenario title contains characters like <, >, or &, the HTML could break.

Optional: escape the title

+import html
...
- <summary><strong>Example</strong>: {scenario_title}</summary>+ <summary><strong>Example</strong>: {html.escape(scenario_title)}</summary>

dfetch/commands/format_patch.py (1)

153-162: str() wrapping is redundant — patch_ng.GIT / SVN / PLAIN are already strings.

Very minor: patch_ng.GIT, patch_ng.SVN, and patch_ng.PLAIN are string constants in patch-ng, so return str(required_type) could simply be return required_type. Not a problem, just a nit.