Caution

The Packaging and Development guide is currently undergoing a major overhaul to bring it up to date. The current state you are seeing now is a preview of this effort.

The current version is unstable (changing URLs can occur at any time) and most content is not in properly reviewed yet. Proceed with caution and be aware of technical inaccuracies.

If you are an experienced packager and would like to contribute, we would love for you to be involved! See our contribution page for details of how to join in.

Download a new upstream version

Once in a while you may need to download a new upstream release or check if a newer upstream release exists; for example:

  • When fixing a bug, to rule out that a more recent version may have already fixed the bug.

  • As a source package maintainer, to check for, download, and package a newer upstream release.

Most of the source packages contain a watch file in the debian folder. This is a configuration file for the uscan(1) utility which allows you to automatically search HTTP or FTP sites or git(1) repositories for newly available updates of the upstream project.

Note

If the source package does not contain a debian/watch file, there may be an explanation and instructions in the debain/README.source or debian/README.debian file (if available) that tell you how to proceed.

Best practices

You should download upstream file(s) manually only if there is no automatic download mechanism and you can’t find any download instructions.

Remember that a package may get distributed to hundreds of thousands of users. Humans are the weakest link in this distribution chain, because we may accidentally miss or skip a verification step, misspell a URL, copy the wrong URL or copy a URL only partially, etc.

If you still have to download upstream file(s) manually make sure to verify Cryptographic Signatures (if available). The Signing Key of the upstream project should be stored in the source package as debian/upstream/signing-key.asc (if the upstream project has a signing key).

uscan(1) verifies downloads against this signing key automatically (if available).

Download new upstream version (if available)

Running uscan(1) from the Root of the Source Tree will check if a newer upstream version exists and downloads it:

uscan

If uscan(1) could not find a newer upstream version it will return with the exit code 1 and print nothing to the Standard Output.

uscan(1) reads the first entry in debian/changelog to determine the name and version of the source package.

You can always add the --verbose flag to see more information (e.g., which version uscan(1) found):

uscan --verbose

Check for new upstream version (no download)

If you just want to check if a new update is available, but you don’t want to download anything, you can run the uscan(1) command with the --safe flag from the Root of the source tree:

uscan --safe

Force the download

You can use the --force-download flag to download an upstream release from the upstream project, even if the upstream Release is up-to-date with the source package:

uscan --force-download

Download the source of older versions from the upstream project

If you want to download the source of a specific version from the upstream project you can use the --download-version flag.

Basic syntax:

uscan --download-version VERSION

For example:

uscan --download-version '1.0'

In the special case that you want to download the source for the current version of the source package from the upstream project you can use the --download-current-version flag instead, which parses the version to download from the first entry in debian/changelog file:

uscan --download-current-version

Note

The --download-version and --download-current-version flags are both a best-effort features of uscan(1).

There are special cases where they do not work for technical reasons.

Note

In most cases you actually want to download the source from the Ubuntu Archive and not re-download the source from the upstream project.

How to get the Source from the Archive?

Further Information