Skip to content

docs: refresh release workflow guidance #171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattenarle10 merged 1 commit into from
Oct 6, 2026
Merged

docs: refresh release workflow guidance #171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,31 @@
- Prefer existing primitives from `src/components/primitives` and icons from `lucide-react` through the local `Icon` wrapper.
- User-facing strings should go through `src/locales/*.json` unless the surrounding file already uses fixed product/legal copy.

## publishing boundary

- Do not commit or push internal planning notes, stale issue queues, private todo lists, or agent scratch docs to the public OSS repo.
- If the user asks to "note", "track", or "add to stale docs" without explicitly saying to publish it, keep it in chat or ask where the private note should live.
- Only update public docs (`README.md`, `docs/**`, release notes, tutorials, site copy) when the content is meant for users/contributors or the user explicitly asks to publish it.

## commands

- `bun test` runs focused unit tests.
- `bun run build` runs TypeScript and Vite build.
- `cargo check --manifest-path src-tauri/Cargo.toml` checks the Rust shell.
- `cargo check --release --manifest-path src-tauri/Cargo.toml` checks the release profile used by CI.
- `cargo fmt --manifest-path src-tauri/Cargo.toml --check` checks Rust formatting without changing files.
- `bun run tauri dev` starts the desktop app during UI testing.

## local github workflow

- Keep the primary checkout available for the user's work. For branch, PR, and release work, use a separate worktree off `origin/main` (for example `git worktree add /private/tmp/markamd-main origin/main`) and remove it when the work is merged.
- Start feature work from the current local `main` branch, keep one focused branch, and run the app from that checkout so screenshots test the branch being changed.
- If another dev server occupies port `1420`, run Tauri with a temporary port override, for example `bun run tauri dev --config '{"build":{"beforeDevCommand":"bun run dev -- --port 1421","devUrl":"http://localhost:1421"}}'`.
- Dependabot may re-resolve to a newer version when it rebases. After merging a `tauri` crate bump, run `bun run tauri build --no-bundle`; CI does not catch a mismatch between the crate and `@tauri-apps/api` / `@tauri-apps/cli`.
- Before merging, verify the PR author and GitHub account are `mattenarle10`, inspect comments and reviews, and wait for both `typecheck` and `rust-check` to pass.
- For a release, merge a version-bump PR first, tag the exact merged `origin/main` commit, and watch the tag's `release` workflow through publication. Confirm the GitHub release is public and latest with signed platform assets and `latest.json`.
- Check `https://markamd.vercel.app/` and `/changelog/` after publishing. The site fetches release data at build time; if it is stale, use the site repository's normal Vercel deploy path rather than changing app release metadata.

## release/update notes

- App version is mirrored in `package.json`, `src-tauri/Cargo.toml`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.lock`.
Expand Down
7 changes: 7 additions & 0 deletions docs/release-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ Use this after the version bump commit is ready and before calling the release d

- [ ] App versions match in `package.json`, `src-tauri/Cargo.toml`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.lock`.
- [ ] Release notes exist at `docs/release-notes/vX.Y.Z.md`.
- [ ] Merge the feature PR first, then make the version bump in a separate release PR based on `origin/main`.
- [ ] `bun test` passes.
- [ ] `bun run build` passes.
- [ ] `cargo check --release` passes from `src-tauri`.
- [ ] `bun run tauri build --no-bundle` passes (catches npm and Rust Tauri version mismatches).
- [ ] `git diff --check` is clean.
- [ ] Linux AppImage smoke test passes on Wayland, including the reported Manjaro environment for #107.

Expand All @@ -19,15 +21,20 @@ Use this after the version bump commit is ready and before calling the release d
- [ ] GitHub `release` workflow passes on the tag.
- [ ] GitHub release is public, latest, and has macOS, Windows, Linux, signature, and `latest.json` assets.
- [ ] Download `latest.json` and confirm the version, release notes, platform URLs, and signatures are present.
- [ ] Confirm the release has a single `latest.json` asset and no `latest.normalized.json`.
- [ ] Confirm `latest.json` platform URLs use public `https://github.com/.../releases/download/...` links, not `https://api.github.com/.../releases/assets/...` REST API links.

The tag must resolve to the same commit as `origin/main` (`git rev-parse vX.Y.Z^{}` versus `git rev-parse origin/main`). Use the repository's configured GitHub account, `mattenarle10`, for PR and release operations.

## site refresh

- [ ] Confirm the `notify-site` job ran or the `VERCEL_DEPLOY_HOOK` secret is configured.
- [ ] Check `https://markamd.vercel.app/` shows the new version in download links, schema, footer, and release section.
- [ ] Check `https://markamd.vercel.app/changelog/` starts with the new release notes.
- [ ] If the site is stale, rebuild/redeploy `markamd-site` or push a small site refresh commit.

The landing site reads the latest GitHub release and repository stats at build time. Check the live homepage and `/changelog/` before making a site change; a successful release does not guarantee that a Vercel deploy hook is configured.

## triage

- [ ] Check open issues and PRs after release.
Expand Down
Loading