# Maintenance

Use this guide when changing a package, upgrading software or preparing a release. Build and cleanup commands are covered in [BUILD.md](BUILD.md).

## Change a package

Find the project under `packages/` and edit the files for the change you need:

| Change | File or directory |
| --- | --- |
| Build or runtime dependencies | `debian/control` |
| Configure options and build commands | `debian/rules` |
| Files assigned to each binary package | `debian/split.py`, `.install` files or other recipe helpers |
| Source patches | `debian/patches/` and its `series` file |
| Package version and change description | `debian/changelog` |
| Desktop integration | `packages/session-integration/source/` |

Keep build helpers inside the package's `debian/` directory so the Debian source package can build on its own. Patch maintenance notes belong in the project's `PATCHES.md`, where present.

After editing:

1. Describe the change in `debian/changelog` and choose the package version.
2. Build the affected project using the instructions in [BUILD.md](BUILD.md).
3. Check the resulting package contents, installation and affected behavior.
4. Update the recipe reference after reviewing and validating the change.

For a published package, increase the Debian revision. For example, change `6.8.2-1plasma1` to `6.8.2-1plasma2`. For unpublished work, `clean <project> --accepted` allows rebuilding at the same version.

### The recipe reference

`config/recipes.lock.json` records file hashes, permissions and symlink targets. `check --baseline` compares recipes and native source files with this reference.

An intentional edit will make that comparison fail until the reference is updated. The reference is a record of expected contents, not a separate copy of the recipe. Generated vendor directories are excluded from the normal baseline comparison.

### Rebuild affected consumers

Build order comes from `Build-Depends` in `debian/control`. `--with-deps` builds a project's prerequisites.

After changing a library, also decide which applications or libraries using it need rebuilding. Select those consumers explicitly. The utility does not detect ABI changes or select downstream rebuilds automatically.

## Upgrade to a new software version

1. Obtain the new release from the project or Debian and verify its authenticity.
2. Update the version and description in `debian/changelog`.
3. Update the project's entry in `config/sources.lock.json` as described below.
4. Review patches and build options for compatibility with the new version.
5. Build the package, check its behavior and rebuild affected consumers.

For a non-native package, set `upstream_version` to the software version and `version` to the full Debian package version. Update the `original` archive entry with its URL, filename, size and SHA-256 hash. Its filename must follow the Debian `<source>_<upstream-version>.orig.tar.*` convention.

Additional downloads have their own roles in the same file:

| Role | Contents | Update when |
| --- | --- | --- |
| `original-component` | An additional source archive | That component changes |
| `crate` | A Rust dependency archive | `Cargo.lock` changes |
| `bootstrap` | Official Rust compiler, Cargo or standard library archive | The bootstrap toolchain changes |

Keep pinned crates consistent with `Cargo.lock`, including dependencies for supported target platforms. Preparation assembles `debian/vendor` from those archives and generates its checksum files.

Native packages, such as session integration, use tracked `source/` files rather than an `original` archive. Update their full version in `debian/changelog` and the source lock when releasing changes.

## Update the Debian build base

The build base uses a fixed Debian snapshot. To advance it:

1. Choose the snapshot and update its URLs in `config/debian.sources`.
2. Verify the snapshot's `InRelease` signatures and record their SHA-256 hashes in `config/snapshot-indexes.json`.
3. Update the snapshot value in `config/release.json` and the bootstrap URL in `tools/lib/bootstrap-controller`.
4. Reset the build environment and run setup again, as described in [BUILD.md](BUILD.md).

The Python build and export tools read distribution, architecture, prefix and repository settings from `config/release.json`. The bootstrap and controller scripts and `tools/lib/sbuild.conf` also contain distribution, architecture, snapshot or local repository settings. Keep those files aligned when changing the build target.

Changing the installation prefix also requires updating package recipes and native integration paths.

## Prepare a release

| File | Review |
| --- | --- |
| `config/release.json` | Distribution, repository identity, URL and signing fingerprint |
| `docs/INSTALL.txt` | Installation commands, versions, URL and signing fingerprint |
| `README.md` | Published software versions and project description |

Set `fingerprint` in `config/release.json` to the full primary signing key fingerprint and keep it consistent with `docs/INSTALL.txt`. A signing subkey under that primary key is supported.

Build the complete catalog, check package data and audit the results. Verify installation and a desktop session before publishing. See [BUILD.md](BUILD.md) for repository export and signing commands.

Export creates a local repository directory. Upload that directory separately. Keep private keys, compiled packages, caches and logs out of Git.

## Check package data

| Command | What it checks |
| --- | --- |
| `python3 tools/plasma-next check --all` | Source names, changelogs and private build dependencies |
| `python3 tools/plasma-next check --all --baseline` | Also compares maintained files with the recipe reference |
| `python3 -m unittest discover -s checks -v` | Recipe reference, dependency ordering and source input metadata |
| `python3 tools/plasma-next audit` | Runtime libraries placed in development packages and runtime links that require them |

Source input metadata includes safe filenames, HTTPS URLs, SHA-256 hashes, sizes and supported roles. Download URLs must not point to the Plasma Next publication server.

The library audit examines ELF files and their `DT_NEEDED` entries. Dynamic loading, QML imports and desktop behavior need separate runtime checks.

## Code and documentation style

Use four spaces for Python indentation, one statement per line and descriptive names. Comments should explain behavior or constraints. Keep each Markdown paragraph on one source line, with blank lines between paragraphs.

Use Ruff to format and check Python changes:

```bash
ruff format tools checks
ruff check tools checks
```