Extend documentation

[spoorcc]

• Add more details on multiple patches
• Problems solved
• Additional example

Summary by CodeRabbit

Release Notes

• Documentation
  • Added "Problems DFetch Solves" section outlining key capabilities including code reuse, multi-repo management, vendoring, patching, and VCS-agnostic dependency management.
  • Clarified that multiple patch files are now supported and applied sequentially to dependencies.
  • Updated workflow documentation and diagrams to reflect enhanced patch handling.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The PR updates documentation across multiple files to clarify that DFetch's patch field supports multiple patches applied sequentially. Changes include a new README section, updated docstrings, manifest documentation, and a UML diagram reflecting iterative patch application.

Changes

Cohort / File(s)	Summary
Documentation & Docstring Updates README.md, dfetch/commands/diff.py, dfetch/manifest/project.py, dfetch/project/metadata.py, doc/manifest.rst, doc/vendoring.rst	Added "Problems DFetch Solves" section to README; updated command documentation phrasing in diff.py; clarified patch attribute documentation to reflect support for single or multiple patches; updated manifest field description and vendoring guide to reference multiple patches
UML Diagram Updates doc/static/uml/update.puml	Modified conditional check from "Patch given?" to "Patches given?" and introduced loop construct with "while (More patches?)" to iteratively apply multiple patches

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Possibly related PRs

• Update dfteched dependencies #882: Updates docs/metadata to describe multiple patches support and uses patch field with multiple patch files in manifests.

Suggested labels

documentation

Suggested reviewers

• ben-edna

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Extend documentation' accurately describes the main focus of the pull request, which updates and expands documentation across multiple files (README, RST docs, UML diagrams) and clarifies multi-patch handling, problems solved, and examples.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% 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 docstrings

---

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: 0

🧹 Nitpick comments (1)

dfetch/commands/diff.py (1)

67-70: Consider minor phrasing improvement.

The documentation accurately describes the multi-patch workflow and provides clear instructions. The option to create an additional patch for unrelated changes aligns well with the multi-patch support.

✨ Optional phrasing improvement

For slightly better flow, consider:

-First step is to reverse the original patch, using
+The first step is to reverse the original patch using

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b9f4239 and 9c72e34.

📒 Files selected for processing (7)

• README.md
• dfetch/commands/diff.py
• dfetch/manifest/project.py
• dfetch/project/metadata.py
• doc/manifest.rst
• doc/static/uml/update.puml
• doc/vendoring.rst

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2026-01-02T22:46:53.305Z

Learnt from: spoorcc
Repo: dfetch-org/dfetch PR: 904
File: script/package.py:10-18
Timestamp: 2026-01-02T22:46:53.305Z
Learning: In dfetch's script/package.py, importing dfetch.__version__ directly is acceptable and intentional; if dfetch is not installed in the environment, the packaging job should fail explicitly rather than handling the import error gracefully.

Applied to files:

• README.md

📚 Learning: 2025-12-31T10:55:28.644Z

Learnt from: spoorcc
Repo: dfetch-org/dfetch PR: 895
File: dfetch/commands/check.py:133-142
Timestamp: 2025-12-31T10:55:28.644Z
Learning: In dfetch, when determining ignored files for a project, the VCS detection should use the superproject's VCS type (where the manifest is located), not the fetched project's VCS type. The ignored files are then queried from the project's destination path using the superproject's VCS system.

Applied to files:

• dfetch/commands/diff.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (15)

• GitHub Check: build / Build wheel 📦
• GitHub Check: build / build (ubuntu-latest)
• GitHub Check: build / build (windows-latest)
• GitHub Check: build / build (macos-latest)
• GitHub Check: Codacy Static Code Analysis
• GitHub Check: run / run (windows-latest, 3.10)
• GitHub Check: DevContainer Build & Test
• GitHub Check: run / run (macos-latest, 3.13)
• GitHub Check: run / run (windows-latest, 3.13)
• GitHub Check: run / run (windows-latest, 3.11)
• GitHub Check: run / run (windows-latest, 3.14)
• GitHub Check: run / run (windows-latest, 3.12)
• GitHub Check: run / run (windows-latest, 3.9)
• GitHub Check: run / test-cygwin
• GitHub Check: test / test

🔇 Additional comments (8)

doc/vendoring.rst (2)

257-259: Documentation clarification on multi-patch support is well integrated.

The expanded explanation clearly conveys that the patch attribute supports both single and multiple patch files applied in sequence. This aligns well with the best practices section's emphasis on minimizing local modifications.

---

333-333: Good addition of real-world Dfetch example.

Adding the Red Jackets Jazzband project provides readers with another concrete reference implementation using Dfetch.

dfetch/project/metadata.py (1)

129-131: Accurate docstring update reflecting list-based patch storage.

The change from singular to plural correctly reflects the property's return type and the implementation's use of always_str_list() to normalize patches to a list. The supporting comment on line 55 confirms this is an intentional feature evolution.

dfetch/manifest/project.py (1)

226-228: Multi-patch documentation is clear and operationally important.

The expanded explanation emphasizes that patches are applied sequentially on each fetch, which is a crucial operational detail for users. The clarification that both single and multiple patches are supported maintains backward compatibility while documenting the new capability. Implementation via always_str_list() on line 320 aligns perfectly with this documentation.

doc/static/uml/update.puml (1)

48-51: LGTM!

The UML diagram correctly reflects the new multi-patch workflow with an iterative loop structure. The PlantUML syntax is valid and the logic accurately represents sequential patch application.

doc/manifest.rst (1)

95-95: LGTM!

The documentation accurately reflects support for multiple patches and maintains consistent phrasing with other documentation updates in this PR.

dfetch/commands/diff.py (1)

4-6: LGTM!

The updated documentation provides clearer phrasing and correctly introduces the "superproject" terminology with an explanation. The technical details accurately reflect that patches use the superproject's VCS.

README.md (1)

40-47: Link is accessible. The external link to GitLab's inner sourcing documentation (HTTP 200) is working. The new "Problems DFetch Solves" section is well-structured, accurately represents the project's capabilities, and all bullet points are clear and grammatically sound.