Files
app__cliphoard/RELEASING.md

145 lines
4.9 KiB
Markdown

# 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
```bash
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:
```bash
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
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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.