docs: expand patching how-to into a mature guide

[spoorcc]

Add a Prerequisites section explaining that dfetch diff needs a
committed upstream baseline before edits are made.

Add an "Upgrading the upstream version" section with three explicit
outcome paths: clean apply, fuzz-apply (refresh patch), and conflict
(manual resolution + update-patch).

Add a Troubleshooting section covering the five most common failure
messages users encounter with patches.

Expand the manifest wiring section to cover patch file organisation
conventions and the behaviour of update-patch with multiple patches
(always updates the last entry).

Expand the format-patch section to document the --output-directory flag.

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01DsDq9BdiWvfxtL9HMvtmaa

Summary by CodeRabbit

• Documentation
  • Updated the patching guide to cover the full patch lifecycle across upgrades, including creating patches, wiring them into the manifest, refreshing them, and re-applying after upstream version changes.
  • Clarified prerequisites (how diffs are computed, required working directory cleanliness, and what’s included/excluded in patch contents).
  • Expanded multi-patch behavior and added clearer workflows for clean apply, fuzz warnings, and patch conflicts.
  • Improved “contributing patches upstream” guidance and added troubleshooting for common patch failures (e.g., no diffs found, missing manifest entries, skipped refresh reasons).

[coderabbitai]

Warning

Review limit reached

@spoorcc, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 52 minutes and 55 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 18561339-9bb0-46cf-9805-e3e3f2d2a34b

📥 Commits

Reviewing files that changed from the base of the PR and between cf1cee3 and bba90a0.

📒 Files selected for processing (1)

• doc/howto/patching.rst

Walkthrough

Expands and rewrites doc/howto/patching.rst to clarify the full patch lifecycle, prerequisites (baseline computation, commit requirements, diff scope), patch content inclusions/exclusions, manifest wiring, multi-patch organization, the dfetch update-patch refresh sequence, upstream version upgrade outcome paths, upstream contribution steps, and a new troubleshooting section.

Changes

Patching How-To Documentation

Layer / File(s)	Summary
Lifecycle overview, prerequisites, and patch contents doc/howto/patching.rst	Rewrites the full lifecycle and Before-you-begin sections to clarify baseline computation via .dfetch_data.yaml, the commit-before-edit requirement, and what dfetch diff captures. Adds a "What goes into the patch" subsection listing included changes and always-excluded files.
Manifest wiring, validation, and multi-patch organization doc/howto/patching.rst	Expands patch-wiring with re-application semantics on dfetch update, a dfetch update --force validation workflow, path resolution relative to dfetch.yaml, and commit guidance. Clarifies that dfetch update-patch always refreshes the last patch in the manifest list.
Refreshing a patch: update-patch sequence and preconditions doc/howto/patching.rst	Rewrites "Refreshing a patch" to describe dfetch update-patch as an explicit four-step sequence and adds the requirement of no uncommitted changes in the superproject project directory before running the command.
Upstream version upgrade paths and contributing patches upstream doc/howto/patching.rst	Replaces the upgrade section with outcome-based guidance (clean apply, fuzz warnings, manual conflict resolution) and updates the contribution section with --output-directory guidance and a dry-run applicability check.
Troubleshooting section doc/howto/patching.rst	Adds/expands troubleshooting entries covering no-diff scenarios, patch failure after upstream bumps, and three update-patch skip causes: uncommitted changes, project never fetched, and missing patch: entry.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• dfetch-org/dfetch#936: Updates the same patching workflow documentation with changes to multiple-patch support and refresh/application order semantics in doc/howto/patching.rst.
• dfetch-org/dfetch#1105: Modifies doc/howto/patching.rst command example blocks and invocation formatting, directly overlapping the file changed in this PR.
• dfetch-org/dfetch#1288: Modifies doc/howto/patching.rst to clarify refresh and update-patch behavior, directly overlapping the lifecycle and troubleshooting content in this PR.

Suggested labels

documentation

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: expanding the patching how-to documentation into a comprehensive guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/improve-patching-docs-qtdida

---

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

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@doc/howto/patching.rst`:
- Around line 336-372: Update the troubleshooting section to match the actual
dfetch tool output by making three corrections: in the "skipped — Uncommitted
changes" message, replace the em dash with a hyphen; in the "skipped — the
project was never fetched" message, replace the em dash with a hyphen and change
"never fetched" to "never fetched before"; and in the "skipped — there is no
patch file" message, replace the em dash with a hyphen. These changes ensure the
documented messages match exactly what users will see when running dfetch
commands.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9da0d37b-60e6-4fa7-ad60-a472eba2f6cb

📥 Commits

Reviewing files that changed from the base of the PR and between c6155b9 and cf1cee3.

📒 Files selected for processing (1)

• doc/howto/patching.rst