Skip to content

Release Workflow

Guide to releasing a new version of gaslamp using the automated release tools.

Overview

The release process is automated through task commands that handle version bumping, release notes generation, bundling, and GitLab publishing. All steps are designed to be run sequentially.

Release Steps

1. Commit Changes

Commit all your changes using conventional commits format:

Bash
git add .
git commit -m "feat: add new feature"

The version bump is determined automatically from your commit messages.

2. Update API documents

Bash
task docs:api

3. Preview Version Bump

Before committing any changes, preview the next version bump based on conventional commits:

Bash
task bump:check

This is a dry run that shows what version bump will be applied without making changes. Review the output to ensure the version level is correct.

4. Bump Version

Bump the version based on your commits:

Bash
task bump:patch    # for patch releases (0.50.0 → 0.50.1)
task bump:minor    # for minor releases (0.50.0 → 0.51.0)
task bump:major    # for major releases (0.50.0 → 1.0.0)

This will:

  • Update version in package.json and pyproject.toml
  • Update uv.lock
  • Run format, test, and build
  • Create a version commit

5. Push Tags

Push all tags to remote:

Bash
task push:tags

This will:

  • Push git tags to remote
  • Include the bundled library

6. Create GAS Version Snapshots

Create version snapshots for both gaslamp and pilotlamp Google Apps Script projects:

Bash
task clasp:version -- 0.50.0

This registers the version with clasp for deployment tracking.

7. Update and commit VERSIONS.toml

Bash
# edit VERSIONS.toml
git add VERSIONS.toml
git commit -m "chore: update VERSIONS.toml"

8. Generate Release Notes

Create and fill in the release notes file from the template:

Bash
task docs:release -- 0.50.0

This generates docs/releases/0.50.0.md from the template. Fill in the release notes with:

  • What Changed - Summary of changes
  • What's New - New features
  • Added/Changed/Fixed sections
  • Breaking Changes and compatibility information
  • Migration guides if needed

Important: Do not modify the template file itself. Only fill in the generated release notes.

After editing, commit the release notes:

Bash
git add docs/releases/0.50.0.md
git commit -m "docs(release): add 0.50.0 release notes"

9. Create GitLab Release

Create the release on GitLab with the release notes:

Bash
task push:release -- 0.50.0

This will:

  • Create GitLab release with release notes
  • Make the release visible in GitLab

Complete Release Example

Bash
# 1. Commit your changes (if not already done)
git add .
git commit -m "feat: new feature"

# 2. Update API document
task docs:api

# 3. Check what version bump will be applied
task bump:check

# 4. Bump version (choose level)
task bump:patch   # or bump:minor / bump:major

# 5. Push tags
task push:tags

# 6. Create GAS version snapshots
task clasp:version -- 0.50.0

# 7. Update and commit VERSIONS.toml

# edit VERSIONS.toml
git add VERSIONS.toml
git commit -m "chore: update VERSIONS.toml"

# 6. Generate and fill in release notes
task docs:release -- 0.50.0
# Edit docs/releases/0.50.0.md with release details
git add docs/releases/0.50.0.md
git commit -m "docs(release): add 0.50.0 release notes"

# 7. Create GitLab release
task push:release -- 0.50.0

Key Notes

  • Version Detection: Conventional commits determine the version bump level (patch, minor, major)
  • Release Notes: Use the template in docs/releases/template.md but do not modify it directly
  • User/Claude Split: Version bump level is chosen by the user; all other release steps are handled by Claude
  • Bundle Included: task push:tags automatically includes the bundled library
  • Breaking Changes: Always document breaking changes in release notes with migration guidance

Troubleshooting

Version bump didn't apply correctly

Run task bump:check to preview before committing.

Release notes file not created

Ensure you're using the correct format: task docs:release -- X.Y.Z (no v prefix)

GitLab release not appearing

Verify that task push:release completed successfully and check GitLab repository releases page.

  • Build — Type-check TypeScript
  • Bundle — Bundle source for Google Apps Script
  • Push — Push to Google Apps Script via clasp
  • Docs — Build and preview documentation
  • Naming Guidelines — Commit message format