1 files changed, 52 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..2a8fb52
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,52 @@
+<!-- -*- mode: markdown; -*- -->
+
+# Handling new upstream releases #
+
+Upstream recently moved their third party assets to a separate git
+repository.  Their build scripts clone this git repository as part of
+the build.  The stated purpose is for easier repository access control
+and bug triage: as far as Debian is concerned, the assets repository
+does not belong in its own source package.
+
+To work around this we maintain a pre-DFSG upstream branch which has
+the third party assets present as a git-subtree(1).  New upstream
+versions are merged into this branch.  We then perform DFSG-cleaning
+on an emphemeral branch and tag the result, so that gbp can generate
+orig tarballs.  Finally the tag is merged into our master Debian
+packaging branch.  Step-by-step, supposing upstream releases version
+1.2.3:
+
+1. git remote add upstream https://github.com/gorhill/uBlock
+2. git remote update
+3. git checkout pre-dfsg
+4. git merge 1.2.3
+5. git subtree pull -P uAssets https://github.com/uBlockOrigin/uAssets master
+6. git checkout -b upstream pre-dfsg
+7. git show master:debian/clean-dfsg.sh | sh
+8. git commit -m "new upstream version 1.2.3 DFSG-cleaned"
+9. git tag 1.2.3+dfsg
+10. git checkout master
+11. git branch -D upstream
+12. git merge 1.2.3+dfsg
+13. Update debian/changelog for new version.
+14. Ensure that debian/copyright is up-to-date with {u,}assets/ublock/
+    dir.
+    Find new non-free filters: `git diff --stat 1.2.2+dfsg..1.2.3+dfsg --  uAssets/thirdparties/`
+15. Update the upstream changelog with `debian/rules get-orig-changelog`.
+16. Cut the Debian release with gbp buildpackage.
+17. git push --tags :
+18. Upload to ftp-master with your favourite tool
+
+## Possible improvements ##
+
+TODO: fold steps 2--11 into clean-dfsg.sh e.g. `% clean-dfsg.sh 1.2.3`
+
+TODO: instead, maintain a dfsg-clean branch with the deletions.  Then
+can just do: git merge new.version && git tag new.version-dfsg
+
+## Original setup of the pre-dfsg branch ##
+
+1. git checkout -b pre-dfsg 1.2.2
+2. git subtree add -P uAssets https://github.com/uBlockOrigin/uAssets master
+
+ -- Sean Whitton <spwhitton@spwhitton.name>, Sun,  6 Nov 2016 14:01:10 -0700