release-dev-project

Release Dev Project

End-to-end release workflow for the user's public development projects. Handles everything from committing to creating a GitHub release with a .deb artifact attached.

Prerequisites

• Current directory is a git repo with a GitHub remote
• The project has a build system that produces a .deb package (check for build.sh, Makefile, Cargo.toml with cargo-deb, setup.py/pyproject.toml, or a debian/ directory)
• gh CLI is authenticated

Steps

1. Assess the project

• Read the repo structure to understand the build system
• Identify where the version number lives:
  • Cargo.toml (Rust)
  • pyproject.toml or setup.py or __init__.py with __version__ (Python)
  • package.json (Node)
  • VERSION file
  • Debian changelog or control file
• Identify how the .deb is built:
  • build.sh script in the repo root
  • cargo deb
  • dpkg-buildpackage
  • Custom build scripts
• Check if the project is currently installed locally (e.g. dpkg -l | grep <name>, which <name>)

2. Commit and push all changes

• Stage ALL changed and untracked files (respect .gitignore)
• Write a clear commit message summarizing the changes
• Push to the remote (origin, current branch)
• If there are no changes to commit, skip to step 3

3. Increment the version

• Default to patch bump (e.g. 1.2.3 -> 1.2.4)
• If $ARGUMENTS contains minor, bump minor (e.g. 1.2.3 -> 1.3.0)
• If $ARGUMENTS contains major, bump major (e.g. 1.2.3 -> 2.0.0)
• If $ARGUMENTS contains a specific version like v2.0.0 or 2.0.0, use that exact version
• Update the version in ALL places it appears (source code, build config, debian metadata)
• Commit the version bump: chore: bump version to vX.Y.Z
• Push the version bump commit

4. Build the .deb package

• Run the project's build process:
  • If build.sh exists: ./build.sh
  • If Rust project with cargo-deb: cargo build --release && cargo deb
  • If Python project: build using the project's packaging setup
  • If custom: follow whatever build instructions exist in the repo
• Locate the resulting .deb file (usually under target/debian/, dist/, or build/)
• If the build fails, stop and report the error — don't proceed to release

5. Update local installation

• Install the new .deb:

  sudo dpkg -i <path-to-deb>
  sudo apt-get install -f -y  # fix any missing deps
  

• Verify the installed version matches what we just built:

  dpkg -l | grep <package-name>
  

• If the project uses a venv or non-deb install method (like /opt/<name>/), update that instead by copying the new source files

6. Create GitHub release

• Create a git tag for the new version: vX.Y.Z
• Push the tag
• Create a GitHub release using gh:

  gh release create vX.Y.Z \
    --title "vX.Y.Z" \
    --generate-notes \
    <path-to-deb>
  

• The --generate-notes flag auto-generates release notes from commits since the last release
• If there's a meaningful summary to add beyond auto-generated notes, prepend it to --notes

7. Report

Tell the user:

• New version number
• What was committed and pushed
• Build result
• Local installation status
• GitHub release URL

Version Detection Heuristics

When no obvious version file exists, search in this order:

1. Cargo.toml → version = "X.Y.Z"
2. pyproject.toml → version = "X.Y.Z"
3. package.json → "version": "X.Y.Z"
4. **/__init__.py → __version__ = "X.Y.Z"
5. setup.py → version="X.Y.Z"
6. VERSION file
7. Latest git tag matching v*

Notes

• Always use Title Case for repo names when creating anything on GitHub
• If no .deb build system exists yet, ask the user if they want you to set one up before proceeding
• If the project is a Python venv app (like VoiceType at /opt/voicetype/), update the installed source files directly instead of building a .deb
• For projects that are NOT debian-packaged, skip step 4 and 5 — just do the GitHub release with source archives
• If $ARGUMENTS contains --no-install, skip local installation (step 5)
• If $ARGUMENTS contains --no-deb, skip .deb build and just create the GitHub release without artifacts