Video Demo

A video demo of updating a package is available in Debian's peertube instance.

Quickstart guide

This Wiki covers steps to take after a package has been successfully updated. Read https://wiki.abrahamraji.in/updating-deb-pkgs/ on how to update a package to the new upstream version. pkgjs-easy-to-update command from pkg-js-tools can give you a list of packages that are easy to update.

TL;DR

In case you couldn't read the long post, here's is a summary. The package being updated here is node-require-directory, though the same steps would apply to any Debian package

  1. Clone the current repo gbp clone --pristine-tar git@salsa.debian.org:js-team/node-require-directory. Note: If you run only git clone, it will only create master branch, you should create upstream and pristine-tar branches locally by running git checkout upstream; git checkout pristine-tar; git checkout master

  2. Download new upstream release tarball using uscan --verbose or use "Step 2, Option 2" above to manually download the new upstream release tarball.

  3. Import the orig.tar.gz using gbp import-orig --pristine-tar ../<upstream_version.orig.tar.gz>.

  4. Add a new section to changelog by running gbp dch -a. It'll automatically update the version number if there are no UNRELEASED entries already. If the version in the changelog is not updated automatically, you need to update it manually to the new upstream version you are importing by running (dch -e) this will automatically open the debian/changelog file for editing.

  5. Build the package using dpkg-buildpackage

  6. Make it lintian clean (use TeamUpload instead of nmu)

  7. Make sure to commit logically every file modified after running (debclean) to clean out dpkg-buildpackage generated files.

  8. Update the debian/changelog file with gbp dch -a to automatically populate the file with commit messages

  9. Build in clean chroot (using tools like sbuild)
  10. Run autopkgtest in a clean chroot (autopkgtest -B ../foo.deb -- schroot unstable-amd64-sbuild)
  11. Squash related commits to have a clean git history, see https://www.git-tower.com/learn/git/faq/git-squash

  12. Check if the update is a Breaking Change and follow the instructions below

Breaking changes

Consult Javascript/Transitions/Policy before uploading breaking changes to unstable. As per https://semver.org major updates(e.g If current version is 2.3.4, then 3.0 is a major update) of libraries with versions greater than 1.0 and minor updates(e.g If current version is 0.10 then 0.11 is a minor update) of libraries with versions less than 1.0 can have breaking changes. Please note that all libraries may not be following semver compliant releases so it is a good idea to check upstream change log or other documentations to confirm if a release includes any breaking changes.

Pushing to Salsa after successfully updating

  1. Create an account in salsa.debian.org and login
  2. Fork the project to your account (there will be a fork button in the repo page)
  3. Change git origin to your fork

   git remote remove origin
   git remote add origin <clone url of your repo>
   git push -u --all --follow-tags

Need help?

Check Javascript/Nodejs/Npm2Deb if your problem (for example if you have to fix some problems reported by lintian) is already documented there. If not contact Javascript team describing your problem and explaining what all things you tried already.