claude-code-usage-bubble/plans/260516-1730-github-release-auto-update/phase-03-docs-and-release-process.md

phase, title, status, priority, effort, dependencies

phase	title	status	priority	effort	dependencies
3	Docs and release process	in_progress	P2	1h	2

Phase 3: Docs and release process

Overview

Now that v0.1.x ships out of CI, update the user-facing docs to point people at the GitHub Release instead of "build from source", and write a short maintainer checklist that future-me can follow to cut a release without re-deriving it from this plan.

Requirements

Functional

• README.md "Install" section points to the Releases page and the SmartScreen warning.
• A new docs/release-process.md (one page) lists the cut-a-release steps: bump Cargo.toml, commit, tag, push.
• Keep the "build from source" path as a secondary option for developers.

Non-functional

• docs/release-process.md under 60 lines.
• No CHANGELOG.md — the GitHub auto-generated release notes are the changelog.

Architecture

The README has one "Install" section (README.md:56-66). Replace it with a two-track structure:

Install
├── Download binary (recommended, one paragraph + SmartScreen note)
└── Build from source (existing block, kept verbatim)

Related Code Files

• Modify: README.md (Install section)
• Create: docs/release-process.md

Implementation Steps

1. README.md — replace the "Install" section. Sketch:

   ## Install
   
   ### Download the latest release
   
   Grab `claude-code-usage-bubble.exe` from the
   [Releases page](https://github.com/tiennm99/claude-code-usage-bubble/releases/latest).
   Put it anywhere on disk (e.g. `%LOCALAPPDATA%\ClaudeCodeUsageBubble\`)
   and run it. The app self-updates from the same Releases feed.
   
   First-run note: the binary is unsigned, so SmartScreen will show
   "Windows protected your PC". Click "More info" → "Run anyway".
   Code signing is on the roadmap.
   
   ### Build from source
   
   <existing block: git clone + cargo build --release>
   

2. docs/release-process.md — new file. Sketch:

   # Cutting a release
   
   The `release.yml` workflow builds and publishes on every pushed
   tag matching `v*.*.*`. The workflow asserts that the pushed tag
   matches `Cargo.toml` `version` and **fails fast on mismatch**, so
   the order below matters: bump Cargo *before* you tag.
   
   Steps for a new version:
   
   1. Bump `Cargo.toml` `version` (`X.Y.Z`).
   2. `cargo build --release` locally to refresh `Cargo.lock`.
   3. Commit: `chore: bump version to X.Y.Z`.
   4. Tag and push:
      ```bash
      git tag -a vX.Y.Z -m "vX.Y.Z"
      git push origin main
      git push origin vX.Y.Z
   

   5. Watch the "Release" workflow run; it creates the GitHub Release with claude-code-usage-bubble.exe attached and auto-generated notes.

   Testing without a real tag

   Use the workflow's workflow_dispatch input with a throwaway tag like v0.0.0-test. The release is created as a draft, so it does not show up on the public Releases feed or trigger self-updates for users.

   Versioning

   Semver-ish: bump patch for fixes, minor for features, major for breaking changes (e.g. settings.json schema change). The in-app updater compares Version { major, minor, patch } lexicographically.

3. Verify the Releases page link in the README resolves (it will once Phase 2 has cut at least v0.1.0).

Todo List

• README.md Install section rewritten with two tracks
• SmartScreen note added
• docs/release-process.md created
• Links verified by clicking through (requires Phase 2 v0.1.0 release to exist)

Success Criteria

• A new contributor reading only README.md knows how to install without building.
• A maintainer reading only docs/release-process.md can cut a release without re-reading this plan.
• No mention of "Until packaged binaries are published" remains anywhere.

Risk Assessment

Risk	Likelihood	Mitigation
README link to /releases/latest 404s before first release exists	Certain pre-Phase-2	Land this phase after Phase 2 has cut v0.1.0
Users skip the SmartScreen note and panic	Medium	Bold the "Click More info → Run anyway" line; mention it in the Releases body too if needed

Security Considerations

• The SmartScreen warning is the user's signal that the binary is unsigned. Be honest about it; do not obscure it.
• Recommending %LOCALAPPDATA% as the install location keeps the user inside their writable tree (no UAC needed for self-update).