plasma-next/docs/MAINTAINING.md

Maintenance

Use this guide when changing a package, upgrading software or preparing a release. Build and cleanup commands are covered in 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.
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.

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 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:

ruff format tools checks
ruff check tools checks