bullseye-backports.md

+# Backporting tips
+
+0. Verify the required version of the package is in `testing` (If the version is not in `testing` due to freeze or transitions, use `bullseye-backports-staging` as target in `debian/changelog`). You can use `rmadison <package name>` command to list versions of packages in different suites. Read [official documentation](https://backports.debian.org/Contribute/) and [official building guide](https://wiki.debian.org/BuildingFormalBackports). **Note: This tutorial is also available as a [video demo](https://peertube.debian.social/videos/watch/82befec2-04f6-4369-8955-3b28a843fc6b)**
+
+1. Use `bullseye-backports` branch. `git branch -a` will list all remote branches. **Note: If default branch is `debian/master` instead of `master` then create `debian/bullseye-backports` as the backports branch.**
+    1. If it already exists (which normally means another version is backported), run
+
+       ```
+       git checkout bullseye-backports
+       ````
+
+       Then **merge the tag you want to backport** and **resolve conflicts** (**add changelog entries in chronological order, ie, based on modified time, most recent upload should be on top**).
+
+       ```
+       git merge debian/<version we are backporting> # Resolve conflicts manually.
+       git add debian/changelog
+       git merge --continue
+       ````
+
+    1. If the branch doesn't already exist, you need to create one. The ideal way to do this is **branching off from the tag you need to backport**. This can be done by 
+
+       ```
+       git checkout -b bullseye-backports <tag>
+       ```
+
+1. Add new changelog entry
+
+   ```
+   dch --bpo
+   ```
+
+   Add `* Rebuild for bullseye-backports` as changelog entry. Note: until bullseye is released, manually change `buster-backports` to `bullseye-backports` and `bpo10` to `bpo11`.
+
+1. Commit the changes
+
+   ```
+   git commit debian/changelog -m "Update changelog for bullseye-backports"
+   ```
+
+1. Prepare environment to build for backports
+
+    1. Create a sbuild chroot for bullseye backports. 
+
+       ```
+       sudo auto-apt-proxy sbuild-createchroot --include=eatmydata,gnupg,auto-apt-proxy bullseye /srv/chroot/bullseye-amd64-sbuild http://deb.debian.org/debian
+       ```
+
+    1. Add `bullseye-security`, `bullseye-backports`, `bullseye-backports-staging` and `bullseye-fasttrack` as distribution aliases. This is required because by default, `sbuild` will not consider bullseye chroot for packages with these distributions in changelog. Edit the file `/etc/schroot/chroot.d/bullseye-amd64-sbuild-*`, and add the following line to its end
+
+       ```
+       aliases=bullseye-security,bullseye-backports,bullseye-backports-staging,bullseye-fasttrack
+       ```
+
+       The file will look like the following after editing
+
+       ```
+       [bullseye-amd64-sbuild]
+       description=Debian bullseye/amd64 autobuilder
+       groups=root,sbuild
+       root-groups=root,sbuild
+       profile=sbuild
+       type=directory
+       directory=/srv/chroot/bullseye-amd64-sbuild
+       union-type=overlay
+       aliases=bullseye-security,bullseye-backports,bullseye-backports-staging,bullseye-fasttrack
+       ```
+
+    1. Create a shortcut to build against this chroot.
+
+        1. Create the file `/usr/local/bin/sbuild-bpo` with the following content
+
+           ```
+           sbuild -A -s --force-orig-source -c bullseye-amd64-sbuild --extra-repository='deb http://deb.debian.org/debian bullseye-backports main' --extra-repository='deb http://incoming.debian.org/debian-buildd buildd-bullseye-backports main' --build-dep-resolver=aptitude -d buster-backports "$@"
+           ```
+Note: `buildd-bullseye-backports` will be available only after bullseye is released so the second --extra-repository option can be removed now.
+
+        1. Make it executable
+
+           ```
+           chmod +x /usr/local/bin/sbuild-bpo
+           ```
+
+1. Build package against backports by running 
+
+   ```
+   sbuild-bpo
+   ```
+
+1. Check changes file to make sure distribution is marked buster-backports. You can **ignore NMU warning** by lintian. **No need to change standards version** for the backports.
+
+1. Sign and upload `.changes` file
+
+   ```
+   debsign <changes file>
+   dput <changes file>
+   ```
+
+1. Create tag (**only if you uploaded the package**)
+
+   ```
+   gbp tag --debian-branch=bullseye-backports
+   ```
+
+1. Push all changes
+   ```
+   git push -u --all --follow-tags
+   ```
\ No newline at end of file