1# Packaging and releases
2
3Packaging is part of the baseline when the project is meant to be installed, not
4an afterthought. Choose the artifact based on how people will actually use the
5project.
6
7## Choose the artifact
8
9- **Library**: no binary packaging unless examples/tools are part of the repo.
10- **Plain CLI or MCP server**: release archives or cross-compiled binaries are
11 usually enough.
12- **System service**: add service files and consider native packages.
13- **Desktop app**: include desktop files, icons, runtime dependencies, and OS
14 installer/package constraints from the start.
15
16## Version gating
17
18Package tasks should fail on ambiguous versions. Prefer exact tags for release
19packages. For development builds, `VERSION=dev` is fine; for packages, be
20stricter.
21
22For Git-tagged releases, a package task can gate on an exact tag:
23
24```sh
25version=$(git describe --tags --exact-match 2>/dev/null) || {
26 echo "Error: package builds require an exact vMAJOR.MINOR.PATCH tag" >&2
27 exit 1
28}
29version=${version#v}
30```
31
32For jj-backed projects, use the project's agreed jj/git-derived release command
33instead. Do not infer package versions from language build metadata unless the
34project explicitly chose that policy.
35
36## Native Linux packages
37
38Use nFPM when shipping `.deb`, `.rpm`, `.apk`, or Arch-style package artifacts
39from a non-distro package pipeline. Keep package metadata boring, explicit, and
40consistent with the project's chosen license.
41
42Visible mise tasks should be simple: `pkg`, `pkg:deb`, `pkg:rpm`, `pkg:apk`,
43`pkg:arch`. Put version resolution, icon conversion, binary staging, package
44builds, and optional compression in hidden/helper tasks when needed.
45
46UPX is optional. Use it only when size matters; do not assume it works well for
47every OS or binary format.
48
49Document cross-compilation constraints in task descriptions and preconditions
50rather than letting users discover linker or runtime failures.
51
52## Go path
53
54For Go binaries, MCP servers, TUIs, web apps, or Wails releases, read
55[golang/index.md](golang/index.md) first and follow its packaging chain. The Go
56path covers static builds, CGO exceptions, Wails/Linux constraints, and Go
57version-injection policy.