public_docs/sosreport_packaging.md

# sosreport: Building and maintaining deb package

This document is a collection of information on how we go about building the sosreport package and the process of building a new version and then potentially doing a SRU. The main purpose of this document is so that anyone would be able to pick this up, if any one leaves the small team that is looking after sosreport.

## Building the package locally

To attempt to build it locally

```
dpkg-buildpackage -b -us -uc -rfakeroot -m --build-by="arif.ali@canonical.com"
```

This will attempt to build the package locally with the email provided, and the version that is specified in debian/changelog. As of writing this piece of the document, this came out to be

```
sosreport_4.6.1-0ubuntu1_amd64.deb
```

This is great for testing locally, but once we are happy that this is working then we need to use the Launchpad way to upload the source.changes file which will then allow LP to build and the package to be available for testing purposes.

## New release from pull-lp-source

First grab the latest version for a series

```
pull-lp-source sosreport bionic
```

Then run `uscan`, which wil download the latest from github, with the debian folder from lp

```
export DEBEMAIL=arif.ali@canonical.com
uscan
cd sosreport-4.6.1
```

Now update the `debian/changelog` and any other modifications required, below is a sample for the `bionic` update

```
sosreport (4.6.1-0ubuntu0~18.04.1) bionic; urgency=medium

  * New 4.6.1 upstream.

  * For more details, full release note is available here:
    - https://github.com/sosreport/sos/releases/tag/4.6.1

  * d/control:
   - Add 'python3-packaging' as part of the runtime depends.
   - Add 'python3-packaging' as part of the build depends.
   - Add 'python3-yaml' as part of the build depends.
   - Add 'python3-pexpect' as part of the build depends.

  * d/copyright:
   - Sync with upstream

  * New patches:
    - d/p/0002-debian-remove-magic-stderr.patch (LP: #2028666)

  * d/rules:
    - skip running unittests/policy_tests.py due to the avocado dependency

  * Former patches, now fixed:
    - d/p/0002-revert-to-old-style-binary-file-detection.patch

  * Remaining patches:
    - d/p/0001-debian-change-tmp-dir-location.patch

 -- Arif Ali <arif.ali@canonical.com>  Mon, 22 Jan 2024 16:59:20 +0000
```

Now build the source changes file

```
dpkg-buildpackage -S --build-by="arif.ali@canonical.com”
```

Finally push the source.changes to publish the package in the PPA

```
dput ppa:arif-ali/sosreport ../sosreport_4.6.1-0ubuntu0~18.04.1_source.changes
```

## FAQs

### How should the versioning be set

The latest series should have the following scheme for all the revisions we have available

For example, if the version of sos is 4.6.1, then we should have all the
revisions as per the table below. This is assuming `noble` is the latest
development series.

| Version | Series |
|-|-|
| 4.6.1-0ubuntu1 | noble |
| 4.6.1-0ubuntu0~23.10.1 | mantic |
| 4.6.1-0ubuntu0~23.04.1 | lunar  |
| 4.6.1-0ubuntu0~22.04.1 | jammy  |
| 4.6.1-0ubuntu0~20.04.1 | focal  |
| 4.6.1-0ubuntu0~18.04.1 | bionic |

If the package is updated due to security or minor fixes then based on the above, the new version would look like the list below

| Version | Series |
|-|-|
| 4.6.1-0ubuntu2 | noble |
| 4.6.1-0ubuntu0~23.10.2 | mantic |
| 4.6.1-0ubuntu0~23.04.2 | lunar  |
| 4.6.1-0ubuntu0~22.04.2 | jammy  |
| 4.6.1-0ubuntu0~20.04.2 | focal  |
| 4.6.1-0ubuntu0~18.04.2 | bionic |

Reference: https://help.launchpad.net/Packaging/PPA/Uploading