Files
app__cliphoard/RELEASING.md

4.9 KiB

Cliphoard release procedure

Run releases from the repository root. The process produces a source tag, release binary, Debian package, checksums, and a Gitea release.

Prepare

git switch main
git pull --ff-only
git status --short

Choose the next semantic version and matching tag, for example 1.3.0 and v1.3.0. Set the version once for the commands below:

VERSION="1.3.0"
TAG="v${VERSION}"

Update the version in Cargo.toml, the root cliphoard package in Cargo.lock, packaging/debian/control, packaging/build-deb.sh, and the versioned .deb names in README.md. Review changes since the previous tag and write notes covering features, fixes, breaking changes, migration needs, passphrase behavior, and platform requirements.

Verify and build

cargo fmt --all -- --check
cargo test --locked --all-features
cargo clippy --locked --all-features -- -D warnings
cargo build --release --locked --features gui
CLIPHOARD_VERSION="$VERSION" packaging/build-deb.sh
dpkg-deb --info "target/cliphoard_${VERSION}_amd64.deb"
dpkg-deb --contents "target/cliphoard_${VERSION}_amd64.deb"
sha256sum "target/cliphoard_${VERSION}_amd64.deb" target/release/cliphoard > "target/cliphoard_${VERSION}_SHA256SUMS"

The isolated package path is:

docker build -t cliphoard-builder .
docker run --rm -v "$PWD/target:/out" cliphoard-builder

Do not commit target/; retain the exact package, binary, and checksum files for upload.

Commit and tag

Only commit after the gates pass:

git diff --check
git status --short
git add Cargo.toml Cargo.lock README.md packaging/debian/control packaging/build-deb.sh src .agents RELEASING.md
git commit -m "Release Cliphoard ${VERSION}"
git tag -a "$TAG" -m "Release Cliphoard ${VERSION}"

Replace 1.2.0 and v1.2.0 with the actual version.

Push Git

Confirm the remote has not moved since the preparation pull. Never force-push:

git show --stat --oneline HEAD
git show --no-patch --decorate HEAD
git push origin main
git push origin "$TAG"

If the remote changed, stop and reconcile it before pushing.

Publish on Gitea

Pushing Git does not upload ignored target/ files. Create a release for the pushed tag and attach:

  • target/cliphoard_${VERSION}_amd64.deb
  • target/release/cliphoard
  • target/cliphoard_${VERSION}_SHA256SUMS

Using the Gitea web UI: open Releases, choose New Release, select the release tag, enter Cliphoard ${VERSION}, paste the release notes, upload all three files, and publish. Include breaking changes and the plaintext-database deletion warning and commands from README.md.

For API automation, use the repository release-write token stored locally in ~/.gitea_token. The file must contain the raw token on one line, remain user-readable only, and never be printed, pasted into chat, put in shell history, or committed. It is ignored by this repository. Load it into the current process without exposing its value:

test -r "$HOME/.gitea_token"
test "$(stat -c '%a' "$HOME/.gitea_token")" = 600
GITEA_TOKEN="$(tr -d '\r\n' < "$HOME/.gitea_token")"
GITEA_URL="https://git.kindle-techprojects.com"
GITEA_OWNER="haffel-public"
GITEA_REPO="app__cliphoard"
TAG="v${VERSION}"

Verify the token has repository access before creating a release. The command discards the response body so it does not expose repository metadata:

curl --fail-with-body -sS -o /dev/null \
  -H "Authorization: token ${GITEA_TOKEN}" \
  "${GITEA_URL}/api/v1/repos/${GITEA_OWNER}/${GITEA_REPO}"

Create the release, then upload each artifact:

release_json=$(curl --fail-with-body -sS \
  -H "Authorization: token ${GITEA_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg tag "$TAG" --arg name "Cliphoard $VERSION" --arg body "$(cat RELEASE_NOTES.md)" \
      '{tag_name:$tag,target_commitish:"main",name:$name,body:$body,draft:false,prerelease:false}')" \
  "${GITEA_URL}/api/v1/repos/${GITEA_OWNER}/${GITEA_REPO}/releases"
release_id=$(jq -r '.id' <<<"$release_json")
for artifact in "target/cliphoard_${VERSION}_amd64.deb" "target/release/cliphoard" "target/cliphoard_${VERSION}_SHA256SUMS"; do
  curl --fail-with-body -sS -H "Authorization: token ${GITEA_TOKEN}" \
    -F "attachment=@${artifact}" \
    "${GITEA_URL}/api/v1/repos/${GITEA_OWNER}/${GITEA_REPO}/releases/${release_id}/assets?name=$(basename "$artifact")"
done

If an earlier attempt already created the release, query the releases endpoint and upload missing assets instead of creating a duplicate. If no authenticated Gitea web session or usable API token is available, stop after the Git push and resume at publication.

Final smoke check

On a clean machine, install the exact .deb, start Cliphoard, create/unlock the encrypted database, and check tray, popup, autostart, settings, and passphrase flows. Verify artifacts against cliphoard_${VERSION}_SHA256SUMS and record the release URL, tag, checksums, and test results.