# Packaging a new upstream release

## Creating the orig.tar.xz
We need to customize our orig.tar.xz for a couple reasons:

1. Remove some pre-compiled binaries. There used to be a bunch, but upstream
   has cleaned up most of them.
2. Vendor a subset of the git submodules. We only include the submodules that
   are consumed by our build to minimize false positives in security scans.
   This was requested by the Ubuntu security team during the initial MIR.

Note: The "upstream/master" branch referenced here is a local branch that I use to track the upstream master branch. It is not pushed to salsa.

  * `git checkout upstream/master`
  * `git reset --hard edk2-stable<newver>`

Check to see if upstream has added any new git submodules. If they have, we may need to add them to the list of submodules we vendor in `debian/rules`. I usually try a build without adding new submodules to see if any of our variants require them, then go back and add them if they do.

```
git diff edk2-stable<oldver>..edk2-stable<newver> .gitmodules
```

Add a copy of the debian directory, bump the changelog version, and run the `get-orig-source` target:

```
git archive debian/latest -- debian | tar x
dch -v <new.ver>+debian "New upstream release, based on edk2-stable<newver>"
fakeroot make -f debian/rules get-orig-source
```

This will run scripts to remove known binaries and look new ones. `debian/remove-binaries.py` will remove all the binaries listed in `debian/binary-check.remove`. If upstream has dropped the binary, just remove it from `binary-check.remove`. `debian/find-binaries.py` will scan the tree for new binaries based on filename. `debian/binary-check.ignore` contains a list of globs that are assumed to not match binaries. If `find-binaries.py` fails with false positives, add globs to that file to ignore them. `get-orig-source` is idempotent, so you re-run it after making these changes.

## Merge the new upstream release

Checkout the `debian/latest` branch and apply any changes you made to the `debian` directory:

```bash
rm -rf /tmp/debian && mv debian /tmp
git checkout debian/latest
rm -rf debian && mv /tmp/debian debian
```

Apply patches one-by-one so we can see if any of them need refreshing:

```bash
quilt push
```

Drop any that are already applied upstream. If any of them need context to apply, refresh them and update the `Last-Updated` date in their DEP-3 headers:

```bash
quilt refresh
```

Now import the new upstream tarball:

```
gbp import-orig \
  --merge-mode replace \
  --merge --pristine-tar \
  --upstream-branch=upstream/master \
  --debian-branch=upstream/latest \
  --upstream-vcs-tag=edk2-stable<newver> \
  ../edk2_<new.ver>+debian.orig.tar.xz
```

And merge it into `debian/latest`:

```bash
git merge upstream/2026.05+debian --no-commit
```

I use `--no-commit` because the merge will not remove files that upstream has removed. I currently do that manually:

```bash
git diff --diff-filter=D --staged upstream/latest | grep -v debian/
git rm <file1> <file2> ...
```

Commit the merge:

```bash
git merge --continue
```

## License changes
This package currently uses `license-reconciler` to flag things that may require `debian/copyright` updates. It will run in CI, but if you want to catch issues locally:

```bash
lrc
```

## Finalizing
I include changes that are tightly coupled with the new upstream release in the merge commit itself. This includes `debian/binary-check.*`, removed or refreshed patches, and `debian/copyright` updates and the `debian/changelog` changes that open the new release. Since I normally make those changes after the merge itself, I do an interactive rebase to squash them back into the merge commit:

```bash
git rebase --rebase-merges -i salsa/debian/latest
```

## CI
At this stage, you can push to salsa to kick off CI:

```bash
git push --follow-tags salsa pristine-tar
git push --follow-tags salsa upstream/latest
git push --follow-tags salsa debian/latest
```
