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.

Upstream and downstream

An Ubuntu installation consists of packages - copied and unpacked onto the target machine. The Ubuntu project packages, distributes and maintains software of thousands of open source projects for users, ready to install. The collection of Ubuntu packages is derived from the collection of packages maintained by the community-driven Debian project.

An important duty of an Ubuntu package Maintainer is to collaborate with the open source projects the Ubuntu packages are derived from – especially with Debian. We do this by keeping the Ubuntu copies of packages up-to-date and by sharing improvements made in Ubuntu back up to Debian.

Terminology

In the context of open source software development, the analogy of a stream that carries modifications, improvements, and code is used. It describes the relationship and direction of changes made between projects. This stream originates (upwards) from the original project (and related entities like Source Code, authors, and maintainers) and flows downwards to projects (and associated entities) that depend on it.

Ubuntu delta

Ubuntu delta (noun):

A modification to an Ubuntu package that is derived from a Debian package.

Upstream

Upstream (noun):

A software project (and associated entities) that another software project depends on either directly or indirectly.

Examples:

  • Debian is the upstream of Ubuntu.

  • Upstream is not interested in the patch.

Usage note:

  • There can be many layers. For example, Kubuntu is a flavour of Ubuntu, therefore Ubuntu and Debian are both upstreams of Kubuntu.

  • The adjective/adverb form is much more commonly used.

Upstream (adjective, adverb):

Something (usually a code modification like a patch) that flows in the direction or is relative to a software project closer to the original software project.

Examples:

  • Debian is the upstream project of Ubuntu.

  • There is a new upstream release.

  • A pull request was created upstream.

  • A bug was patched upstream.

upstream (verb):

Sending something (usually a patch) upstream that originated from a Fork or project that depended on the upstream project.

Examples:

  • We upstreamed the patch.

  • Can you upstream the bugfix?

Downstream

Downstream (noun):

Similar to Upstream (noun): A software project(s) (and associated entities) that depend on another software project either directly or indirectly.

Example:

  • Ubuntu is a downstream of Debian and there are many downstreams of Ubuntu.

Usage note:

  • The adjective/adverb form is much more commonly used.

  • There can be many layers. For example, Kubuntu is a flavour of Ubuntu, therefore Kubuntu and Ubuntu are both downstreams of Debian.

Downstream (adjective, adverb):

Similar to Upstream (adjective, adverb): Something (usually a code modification like a patch) that flows in the direction or is relative to a software project farther away from the original software project.

Examples:

  • Ubuntu is a downstream project of Debian.

  • The bug is already patched downstream.

  • The bug was reported by a downstream user.

  • Downstream maintainers have submitted a bugfix.

  • The change may affect downstream users.

Downstream (verb):

Similar to upstream (verb): Sending something (usually a patch) downstream that originated from an upstream project.

Example:

  • We downstreamed the patch.

Why do we upstream changes?

Note

The following list does not aim for completeness. There are plenty of other good arguments for why changes should be upstreamed.

  • Decreased maintenance complexity: Think of any Ubuntu package derived from a Debian package that carries a delta. Every time the Debian package gets updated, the Ubuntu package may be subject to a merge conflict when the changes to the Debian package get applied to the Ubuntu package. By upstreaming changes we reduce the maintenance cost to resolve merge conflicts when they occur.

  • Quality assurance and security: Any changes that get upstreamed will also be subject to the quality assurance of the upstream project and the testing coverage that the user base of the upstream project provides. This increases the likelihood of discovering regressions/bugs/unwanted behaviour (especially security-related bugs). Also, be aware that an unpatched security vulnerability in any system could lead to the indirect exposure of other systems.

  • Mutual benefit: By syncing the Debian packages into the Ubuntu package collection, Ubuntu benefits from the upstream maintenance work. In exchange, Ubuntu Maintainers upstream changes to Debian. This results in a win-win situation where both parties benefit from working together.