1 files changed, 100 insertions, 0 deletions
diff --git a/debian/pkg-zsh-workflow-new-upstream-release.md b/debian/pkg-zsh-workflow-new-upstream-release.md
new file mode 100644
index 000000000..d8448bc32
--- /dev/null
+++ b/debian/pkg-zsh-workflow-new-upstream-release.md
@@ -0,0 +1,100 @@
+Transitioning to a New Upstream Version in a Nutshell
+=====================================================
+
+TL;DR: We're more or less using the `gbp import-orig` workflow.
+
+Prerequisites
+-------------
+
+* Having the zsh upstream git repo configured as a git remote named
+  `upstream-repo`. If that's not the case, `dpt import-orig` will
+  create that remote automatically. You can also use `dpt
+  upstream-repo` to create that git remote semi-automatically. Both
+  commands take the upstream git repo URL from
+  `debian/upstream/metadata`.
+
+* Having the package `git-buildpackage` installed for the `gbp`
+  command.
+
+* Having the package `devscripts` installed for the `uscan` command
+  (used by `gbp` and `dpt`).
+
+* Optionally: Having the package `pkg-perl-tools` installed for the
+  `dpt` command, which partially is a convenience wrapper around `gbp`.
+
+Workflow
+--------
+
+When upstream releases a new version, we should follow these steps:
+
+### Donwloading, Importing and Merging the New Upstream Tar-Ball
+
+... and verifying its PGP signature.
+
+    % gbp import-orig --uscan
+
+or
+
+    % dpt import-orig
+
+(`dpt import-orig` implies `--uscan`, but will also call `dch`, so
+you'll need to amend that instead of creating it in the next step. Or
+undo it)
+
+### Create a debian/changelog entry for the new upstream release
+
+Use `gbp dch` as a base and then remove all lines which are not
+debian-specific and which do not relate to a Debian bug report. Add
+Debian bug report references (`Closes: #nnnnnn`) as necessary.
+
+Use the tagged upstream commit and the merge commit where the upstream
+release was merged into the debian branch as referred commit ids.
+
+Example:
+
+    * [9dbde9e,bf8b7f7] Import new upstream release candidate X.Y-test-Z
+      + [dc2bfeee] Have V07pcre fail if PCRE was enabled by configure
+        (config.modules) but failed to load for any reason. (Closes: #909114)
+
+    [ Axel Beckert ]
+    * [abcd1234] Some debian-specific change generated by gbp dch from
+      the git commit message.
+      
+Commit it as follows:
+
+    % git add debian/changelog
+    % git commit -m "Update debian/changelog for new upstream release" -m "Gbp-Dch: Ignore"
+
+### Remove all quilt patches which are applied upstream
+
+All patches applied (or fixed otherwise) upstream should be removed
+from `debian/patches` directory and the `debian/patches/series` file.
+
+Example:
+
+    % quilt push -a
+    % quilt pop -a
+    % git rm debian/patches/cherry*
+    % $EDITOR debian/patches/series
+    % git add debian/patches
+    % quilt push -a
+    % quilt pop -a
+    % git commit -m "Remove all patches applied upstream"
+
+### Update `debian/NEWS`
+
+Review the upstream `NEWS` file and the list of compatibilities in the upstream
+`README` file (starts at line 33) and add them to `debian/NEWS`:
+
+    % less NEWS
+    % less +33 README
+    % dch --news
+    % git commit -m "Add NEWS based on incompatibilities listed in upstream's README." -m "Gbp-Dch: Ignore"
+
+### After a build, restore what the clean target removed
+
+Use any of these three commands:
+
+    % debian/rules restore-cleaned-files
+    % make -f debian/rules restore-cleaned-files
+    % git status --porcelain | egrep '^ D ' | cut -c4- | xargs --no-run-if-empty git checkout