<a id="bugfixing-workflow"></a>

# Bugfixing workflow

This guide walks through the process for fixing bugs in Ubuntu. When you find a problem, obtain the code, work on a solution, test the fix, push your changes to [Launchpad](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/glossary.md#term-Launchpad), and request a review and merge.

#### ATTENTION
There is information placed within angle brackets in this guide. Ensure you replace them with the appropriate values. For example, replace `<package-name>` with the name of the package you are working on.

## Find a bug to fix

Start by identifying an issue to work on. This can be a bug you encountered while using an application, a problem described in a bug report, or a known issue in the Ubuntu community.

You can also explore known bugs using these resources:

- [Bite-size bugs on Launchpad](https://bugs.launchpad.net/ubuntu/+bugs?field.tag=bitesize): Small, well-scoped bugs that are great for new contributors.
- [One hundred paper cuts](https://launchpad.net/hundredpapercuts): Minor bugs that negatively affect the user experience.
- [Launchpad bug tracker](https://bugs.launchpad.net/ubuntu) and [Debian’s bug trackers](https://www.debian.org/Bugs/): Issue reports for Ubuntu and Debian packages.

## Evaluate the bug report

Once you find a bug report on Launchpad that you want to work on, evaluate the bug.

Read the bug description carefully and look for:

- steps to reproduce the problem
- crash logs or terminal output
- details about the affected version and package
- attached `.crash` files or [Apport crash files](https://documentation.ubuntu.com/project/contributors/bug-fix/evalute-the-bug.md#evaluate-the-bug)

For example, the [Postconf segfaults every 5 minutes](https://bugs.launchpad.net/ubuntu/+source/postfix/+bug/1753470) bug report shows a segmentation fault in `postconf` on Ubuntu 18.04 LTS. It includes logs from `/var/log/kern.log`, shell commands that reproduce the issue, and metadata about the system environment. This information helps confirm whether the bug still affects current versions and if the report is complete.

If the bug includes a `.crash` file, extract and inspect the stack trace. Use the information to better understand where the failure occurred in the code.

For more details, see [Evaluate the bug](https://documentation.ubuntu.com/project/contributors/bug-fix/evalute-the-bug.md#evaluate-the-bug).

## Identify the source package

After selecting a bug to fix, identify the source package that contains the code related to the issue.

Start by identifying the name of the binary package. To identify the package that owns a file installed on your system, use:

```none
dpkg -S <path-to-file>
```

#### NOTE
Replace `<path-to-file>` with the full path to the file.

For example, run:

```none
dpkg -S /usr/games/bumprace
```

Running the command returns an output similar to:

```none
bumprace: /usr/games/bumprace
```

In the preceding output, the part before the colon is the name of the binary package.

#### NOTE
For packages not installed on your system, use `apt-file` to search across all packages. However, `apt-file` is not installed by default and must be set up before use:

```none
sudo apt install apt-file
sudo apt-file update
```

Once set up, run the search command:

```none
apt-file find <filename-or-path>
```

For example, `apt-file find bumprace`.

After identifying the name of the binary package, the next step is to find the source package. Use the following command:

```none
apt show <binary-package-name>
```

For example:

```none
apt show bumprace
```

Check the output for the `Source` field. This field indicates the name of the source package.

It’s possible for the name of a binary package to be the same as its source package. If this is the case, the `apt show <binary-package-name>` command doesn’t display the `Source` field in its output. In such cases, assume the source package name is the same as the binary package name.

## Check if the bug has been fixed

Once you identify the source package, make sure the issue still exists. A fix may already exist in a newer Ubuntu release, in Debian, or upstream. Checking first saves time and avoids duplicate work.

For a detailed walkthrough — including example commands, how to clone and inspect package history with `git-ubuntu`, how to browse Debian’s repositories, and how to search upstream — see [Check if it’s already been fixed](https://documentation.ubuntu.com/project/contributors/bug-fix/check-if-is-it-already-fixed.md#check-if-is-it-already-fixed).

## Offer to help

Once you confirm the issue still exists, a bug report is open, and no one is working on it, you can offer to help. This step signals your interest in resolving the issue and helps prevent duplicated efforts.

Start by commenting on the bug report in Launchpad. Let others know that you intend to work on the issue. Include any relevant details you have, such as:

- when and how the bug occurred
- how you plan to fix the issue, or what you’ve tried so far
- any testing you’ve done or plan to do

If the bug doesn’t yet exist in Launchpad, create a new bug report. Provide a clear title and description. Explain how the issue can be reproduced, and add logs or screenshots if helpful.

## Get the source code

Once you’re assigned to the bug, get the source code for the affected package. You can get the source code using any of these four methods:

- `git-ubuntu`
- `pull-pkg`
- `apt-get source`
- `dget`

For detailed instructions on using these methods to get the source code, see [How to get the source of a package](https://documentation.ubuntu.com/project/contributors/setup/get-the-source-of-a-package.md#how-to-get-the-source-of-a-package).

## Create a patch to fix the issue

You may need to create a patch to make changes to a package. Start by checking where your changes are located. If your changes are only within the `debian/` directory, for example, in `debian/control`, you don’t need to create a patch. However, if you changed upstream source code, that is anything outside `debian/`, then you must create a patch and include it in `debian/patches`.

There are two main methods for creating patches for Ubuntu packages. The method to choose depends on the workflow that the package source uses:

<!-- TODO UMH dupl.? -->
- If the package uses [quilt](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/glossary.md#term-Quilt), use the  tool to create and manage patches. To learn how to create a patch using `quilt`, see [Creating a patch with quilt](https://documentation.ubuntu.com/project/contributors/updating/make-changes-to-a-package.md#creating-a-patch-with-quilt).
- If the package is maintained using `git-ubuntu`, commit your changes directly in Git.

<!-- TODO how do i know? -->

## Documenting the fix

It’s important to document your changes, so future developers can understand your reasoning and assumptions without having to guess.

Explain your changes in the `debian/changelog` file. This file tracks every change uploaded to Ubuntu or Debian, and future developers rely on it to understand what changed, where it happened, and why.

See [Updating the changelog](https://documentation.ubuntu.com/project/contributors/updating/make-changes-to-a-package.md#updating-the-changelog) for details.

## Testing the fix

Run package tests to check that your change doesn’t introduce regressions. Ubuntu uses [autopkgtest](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/glossary.md#term-autopkgtest) to automate this process. You can run tests in several ways:

- in a local virtual machine (VM)
- through a [Personal Package Archive](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/glossary.md#term-Personal-Package-Archive) (PPA) on Launchpad
- in a container

For local testing, use a VM or container. The autopkgtest tool builds test images and runs the tests in an isolated environment. Use this method when you want to debug failures or verify changes before uploading to a PPA. If your testbed needs to reboot or be isolated, use a VM or container as defined in the package’s `debian/tests/control` file.

You can also use PPA-based method whenever possible. It produces results closest to what Launchpad runs for archive packages. After uploading your package to a PPA and building it, trigger tests using the `PPA` tool from `ppa-dev-tools`. You need special permissions to launch these tests. Ask for help in the `#ubuntu-devel` IRC channel if needed.

<!-- TODO UMH link -->

To learn how to set up and run these test methods, see [Running package tests](https://documentation.ubuntu.com/project/contributors/building/run-package-tests.md#how-to-run-package-tests).

<a id="submitting-the-fix"></a>

## Submitting the fix

Once you’ve documented and saved your changes in a new changelog entry, run `debuild`:

```none
debuild -S -d
```

The command signs the changes in the file. After that, submit your fix by opening a merge proposal. For details on how to do this, see the section on [Merge proposal](https://documentation.ubuntu.com/project/contributors/updating/submit-a-merge-proposal.md#how-to-submit-a-merge-proposal).

In many cases, Debian would benefit from the fix as well. Submitting to Debian is considered best practice because it ensures that a wider audience receives the fix. You can submit the fix to Debian by running:

```none
submittodebian
```

Running the preceding command walks you through a series of steps to ensure the bug report ends up in the correct place. Be sure to review the [diff](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/glossary.md#term-diff) again to confirm it doesn’t include unrelated changes you made earlier.

Also, ensure you add a clear description of the fix to the inclusion request.

If everything goes well, you get an email from Debian’s bug tracking system with more information. This may take a few minutes.

Sometimes it’s best to get your fix included in Debian first. It then flows downstream to Ubuntu automatically. In that case, skip the following steps.

For security updates or updates to stable releases, the fix might already be in Debian or intentionally ignored. In these cases, follow the process described here.

<!-- TODO link to the article on Security and stable release updates. -->

If you’re doing a security or stable release update, read the article on Security and stable release updates.

You can also follow this process when dealing with Ubuntu-only packages that don’t build correctly, or with issues that affect Ubuntu specifically.

If you’re submitting your fix to Ubuntu, generate a `debdiff`. A `debdiff` shows the difference between two Debian source packages. The command comes from the `devscripts` package. For full details, see the manual page for .

To compare two source packages, use the `.dsc` files as arguments:

```none
debdiff <package_name>_1.0-1.dsc <package_name>_1.0-1ubuntu1.dsc
```

Compare the original `.dsc` file with the one you generated after making your changes. This generates a patch that your sponsor can then apply locally by using `patch -p1 < /path/to/debdiff`. In this case, redirect the output of the `debdiff` command to a file and attach it to the bug report:

```none
debdiff <package_name>_1.0-1.dsc <package_name>_1.0-1ubuntu1.dsc > 1-1.0-1ubuntu1.debdiff
```

The format of the filename shown in `1-1.0-1ubuntu1.debdiff` has some meaning:

1. `1-` tells the sponsor that this is the first revision of your patch.
2. `1.0-1ubuntu1` shows the version you are working on.
3. `.debdiff` makes it clear that it’s a `debdiff` file.

While this format is optional, it works well and you’re encouraged to use it.

Next, go to the bug report on Launchpad. Log in and click **Add attachment or patch** near the comment box. Attach the `debdiff` and leave a comment. Explain how the patch can be applied and what testing you’ve done.

Here’s an example:

```text
This is a debdiff for Artful applicable to 1.0-1. I built this in pbuilder and it builds successfully, and I installed it, the patch works as intended.
```

Mark the attachment as a patch. This notifies the Ubuntu Sponsors team. Subscribe to the bug report to get updates.

You usually get a review within a few hours to a few weeks. If it takes too long, join `#ubuntu-motu` on IRC and ask for help. Stay in the channel until someone responds and guides you through your next steps.

After the review, the sponsor might upload your fix, request changes, or reject it. If changes are needed, follow the same steps and submit a new `debdiff` to the bug. If the fix is rejected because it’s not a fit for Ubuntu, you might need to send it to Debian instead.

If you have questions, email `ubuntu-motu@lists.ubuntu.com` or join `#ubuntu-motu` on IRC. There you find people who share your passion for improving open source and making the world better.