This package is maintained on salsa.debian.org, using git-buildpackage (gbp),
including the use of `gbp pq` for patches (if any), pristine-tar (via gbp) for
original tarballs, and `gbp dch` for changelog generation.
(This file can be interpreted as Markdown, if you prefer your text with
To update to a new version from upstream:
1. Clone with `gbp clone firstname.lastname@example.org:openxr-team/openxr-sdk-source.git`
2. Create the patch queue, if any, by running `gbp pq import` then
`git checkout debian/sid` (since `pq import` will change your branch).
3. Look at the upstream diff, and see if we may need to adjust the repack
exclusions in `debian/copyright`: if so, do it now.
4. Download the upstream tar.gz file and repack it: use `uscan`
5. Import the new orig source:
`gbp import-orig ../openxr-sdk-source_VERSION~dfsg1.orig.tar.xz`
6. Refresh patches, if any:
- `gbp pq switch` to change to the patch queue branch
- `git rebase debian/sid` to rebase: edit+`git rebase --continue` to fix
patches, or `git rebase --skip` those that are incorporated upstream.
- `gbp pq export` when rebase is complete to update the patch directory.
- Commit changes in debian/patches with appropriate commit message.
7. Use `cme edit dpkg` to update any metadata in the patches or the rest of the
package, as well as check for warnings.
8. Use `cme update dpkg-copyright` together with manual edits of
debian/copyright, debian/copyright-scan-patterns.yml, and
debian/fill.copyright.blanks.yml, repeating until a stable and accurate point
is arrived-at, to update the copyright file according to upstream changes.
`debmake -k` is a useful, independent, but similarly not infallible, check of
9. Update the changelog: `gbp dch` followed by manual editing
- "New upstream release" should be the first bullet point.
- Ensure that the version is right: if not, there was a mistake earlier, find
a maintainer, DM, or DD to help.
- Call out each individual patch added/removed by name, unless all were
removed due to upstreaming.
- Commit changelog update.
10. Build locally (in a pbuilder, with sbuild, or just directly on your machine
with `debuild -uc -us`) as a smoketest.
11. If the local build worked, push to salsa with `gbp push` (to push the
upstream and pristine-tar branches too) and `git push origin debian/sid`,
and make sure that the CI passes.
12. Perform any other maintenance operations.
13. When ready to submit, run `gbp dch --release` to change from UNRELEASED to
unstable and update the timestamp: commit the changes after reviewing them.
14. If you can push to the archive, do that, signing as yourself. Otherwise,
poke your packaging sponsor who will push a (source) package they build and
15. Use `gbp tag --sign-tags --keyid=YOURKEYID` to tag after release, and push
the tag to Salsa too.
Ports to other distributions/versions are also maintained in the same
repository, following DEP14 guidance:
https://dep-team.pages.debian.net/deps/dep14/ See also the official guidance for
backports: https://wiki.debian.org/BuildingFormalBackports To update
backports/ports to other distributions, after releasing to unstable:
1. Check out the other distro's branch, if it exists. If it does not:
- Check out a new branch from debian/sid with the correct name.
- Modify debian/gbp.conf to specify the correct branch
- Modify debian/control's Vcs-Git: field to specify the correct branch with a
-b <branch> suffix.
- TODO: Figure out how to properly modify or constrain salsa-ci.
- Commit these changes.
2. Merge from debian/sid if you didn't just create this branch. (Make sure
dpkg-mergechangelogs from package dpkg-dev is working to get the
debian/changelog merged correctly:
You can run debian/extra/register-dpkg-mergechangelogs.sh to do this setup
for you automatically: ideally, you'd pass --global and have it put in your
user config file instead of the repo config file.)
3. Create a porting changelog entry with the correct distribution and version
suffix, and with a message in the entry like "Rebuild for buster-backports."
- For debian stable backports, `gbp dch --bpo` will get you started (appends
~bpo10 for a backport to Debian 10 "Buster").
- For Ubuntu versions, e.g. append ~ubuntu2004 to the version number for a
port to Ubuntu 20.04 "Focal", etc.
- It appears that gbp handles DEP14 branch names OK, so you can leave the
distribution as UNRELEASED until you're done.
4. Review to see if any packaging changes are needed for this distribution. Be
sure to commit changes and use `gbp dch` to document them in the changelog as
you add them. Known "gotchas" to consider include:
- Be sure to uncomment the `export DEB_LDFLAGS_MAINT_APPEND` line in
debian/rules for distributions older than bullseye where this is not
automatically added. See
5. Try building locally, just as above, on an appropriate
6. Push to salsa.
7. When ready to release, use `gbp dch --release` to update the changelog
timestamp and distribution, commit the changes, and push them. Once you've
built a package to upload, push a signed tag as well, just as above.
- Note that when building a backport package, you should use
`debuild -uc -us -v<LastVersionInTheTargetDistro>` (plus `-S` for a
source-only package, or whatever other flags you need) to make the changes
file comprehensive enough: https://backports.debian.org/Contribute/
Ubuntu updates can be pushed to the Monado PPA:
https://launchpad.net/~monado-xr/+archive/ubuntu/monado Note that packages
pushed there should get an extra `~ppa1` at the end of the version number, to
avoid conflicting with native packages once they get them. (This doesn't
necessarily need to be committed to git, I think.) `debuild -uc -us -S` will do
the build. You may need to add `-sa` if the upload gets rejected. Sign with
debsign - note you must be in the team on launchpad and have your GPG key
uploaded there - then upload with `dput ppa:monado-xr/monado <source.changes>`
-- Ryan A. Pavlik <email@example.com> Wed, 25 Nov 2020 16:36:32 -0600