build-plasmoid-file

Build a .plasmoid File for Distribution

Plasma widgets are distributed on store.kde.org / opendesktop.org as a single archive named <id>-<version>.plasmoid. The .plasmoid file is just a zip of the contents of package/ (no top-level wrapper directory). KDE's "Get New Plasma Widgets" pulls the file attached to the product's Files section — the GitHub repo is irrelevant to GHNS users.

Layout assumption

The repo follows the standard KDE plasmoid layout:

<repo>/
  package/
    metadata.json            ← KPlugin.Version lives here
    contents/
      ui/, code/, config/
  install.sh                 ← used for local install (kpackagetool6)

If the repo doesn't have package/metadata.json, stop and tell the user — this isn't a Plasma 6 plasmoid in the standard layout.

Steps

1. Read current state

• package/metadata.json → read KPlugin.Name, KPlugin.Id, KPlugin.Version.
• Run git status --short and git log -1 --oneline to confirm the working tree is clean (or warn the user if not).

2. Decide the new version

Ask the user only if unclear. Default rules:

• Patch bump (1.3.0 → 1.3.1) — bug fixes, packaging-only changes
• Minor bump (1.3.0 → 1.4.0) — new features, new config options, new UI
• Major bump (1.3.0 → 2.0.0) — breaking changes (config schema rewrites, etc.)

If the user gave an explicit version, use that verbatim. Otherwise propose one based on the recent commits (git log <last-tag>..HEAD --oneline if a tag exists) and confirm.

3. Bump the version

Edit package/metadata.json — change KPlugin.Version to the new value. Don't touch other fields.

4. Build the archive

The .plasmoid is a zip of package/'s contents (the metadata.json must be at the archive root, not inside a package/ directory). Use a (cd package && zip ...) pattern:

cd <repo-root>
ID=$(jq -r '.KPlugin.Id' package/metadata.json)
VER=$(jq -r '.KPlugin.Version' package/metadata.json)
OUT="${ID}-${VER}.plasmoid"
rm -f "$OUT"
( cd package && zip -r "../$OUT" . -x '*.bak' '*~' '.DS_Store' )
ls -lh "$OUT"