From f3ab84751cbd98d7ad19e9af9f85629a32de031d Mon Sep 17 00:00:00 2001
From: Gordon Messmer <gmessmer@redhat.com>
Date: Wed, 8 Jul 2026 14:11:53 -0700
Subject: [PATCH] Document --dry-run option for propose-downstream and
 pull-from-upstream

Add documentation for the new --dry-run flag:
- Update help output sections with --dry-run option
- Add "Dry-run mode" sections to both command docs
- Explain what operations continue in dry-run mode (downloads, syncing, local commits)
- Explain that sources file is updated using fedpkg new-sources --offline
- Explain what operations are skipped (lookaside uploads, pushes, PR creation)
- Provide usage examples and use cases
- Clarify when to use each command (upstream vs dist-git repo)

This complements the packit PR adding --dry-run functionality.

Co-authored-by: Claude <claude@anthropic.com>
Signed-off-by: Gordon Messmer <gmessmer@redhat.com>
---
 docs/cli/propose-downstream.md | 27 +++++++++++++++++++++++++++
 docs/cli/pull-from-upstream.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/docs/cli/propose-downstream.md b/docs/cli/propose-downstream.md
index 61a0be4e4c..fe432723f1 100644
--- a/docs/cli/propose-downstream.md
+++ b/docs/cli/propose-downstream.md
@@ -71,6 +71,31 @@ We newly support `propose-downstream` also for CentOS Stream, see the configurat
   Guidelines](https://fedoraproject.org/wiki/Packaging:SourceURL#Referencing_Source).
 Then it copies the files listed in `files_to_sync` (which by default includes the spec file) from the upstream repo to downstream and creates the downstream PR.
 
+## Dry-run mode
+
+You can use `--dry-run` to test the update process locally without pushing to Fedora infrastructure:
+
+```
+$ packit propose-downstream --dry-run
+```
+
+In dry-run mode, packit will:
+- Download source archives locally
+- Update the `sources` file (using `fedpkg new-sources --offline`)
+- Sync files and generate patches
+- Update the spec file
+- Create local commits in dist-git
+
+But it will **skip**:
+- Uploading archives to lookaside cache (only updates `sources` file)
+- Pushing commits to remote
+- Creating pull requests
+
+This allows you to:
+- Test the update locally before pushing to Fedora
+- Perform local builds (e.g., `fedpkg local` or `rpmbuild`) to verify the changes
+- Inspect the dist-git changes before they go live
+
 ## Help
 
     Usage: packit propose-downstream [OPTIONS] [PATH_OR_URL] [VERSION]
@@ -109,4 +134,6 @@ Then it copies the files listed in `files_to_sync` (which by default includes th
       --upstream-ref TEXT     Git ref of the last upstream commit in the current
                               branch from which packit should generate patches
                               (this option implies the repository is source-git).
+      --dry-run               Prepare dist-git repository locally without pushing
+                              to remote or uploading to lookaside cache.
       -h, --help              Show this message and exit.
diff --git a/docs/cli/pull-from-upstream.md b/docs/cli/pull-from-upstream.md
index 95b71eaa93..cfc7c2cff9 100644
--- a/docs/cli/pull-from-upstream.md
+++ b/docs/cli/pull-from-upstream.md
@@ -21,6 +21,34 @@ upstream release. This command is meant to be called from **dist-git repository*
     the name of the git tag (or `upstream_tag_template` is configured).
 
 
+## Dry-run mode
+
+You can use `--dry-run` to test the update process locally without pushing to Fedora infrastructure:
+
+```
+$ cd /path/to/dist-git/repo
+$ packit pull-from-upstream --dry-run --dist-git-branch f42
+```
+
+In dry-run mode, packit will:
+- Clone or fetch upstream repository
+- Download source archives locally
+- Update the `sources` file (using `fedpkg new-sources --offline`)
+- Sync files from upstream and generate patches
+- Update the spec file
+- Create local commits in dist-git
+
+But it will **skip**:
+- Uploading archives to lookaside cache (only updates `sources` file)
+- Pushing commits to remote
+- Creating pull requests
+
+This allows you to:
+- Test the update locally before pushing to Fedora
+- Perform local builds (e.g., `fedpkg local` or `rpmbuild`) to verify the changes
+- Inspect the dist-git changes before they go live
+
+
 ## Help
 
     Usage: packit pull-from-upstream [OPTIONS] [PATH_OR_URL] [VERSION]
@@ -53,4 +81,6 @@ upstream release. This command is meant to be called from **dist-git repository*
                               available, like in a monorepo configuration. Use it
                               multiple times to select multiple packages.Defaults
                               to all the packages listed inside the config.
+      --dry-run               Prepare dist-git repository locally without pushing
+                              to remote or uploading to lookaside cache.
       -h, --help              Show this message and exit.