Hasami Release Tool

Hasami: BonsAI Release Management Tool #

Hasami is the custom release management tool used across the BonsAI monorepo. The name means “scissors” in Japanese, reflecting its precise role in cutting releases.

Overview #

Hasami manages the entire release lifecycle:

  • Creating structured release notes
  • Bumping versions according to semantic versioning rules
  • Generating and updating changelogs
  • Creating release tags in a standardized format (yyyy-mm-dd)
  • Automating PR creation for changelog updates

Automated Release Process #

Step 1: Release Notes Creation #

Developers create release notes for their changes:

# Start interactive session
hasami

This guides you through:

  1. Selecting the affected project
  2. Choosing the change type (feature, bugfix, misc)
  3. Specifying the version bump (major, minor, patch)
  4. Providing release note content

Release notes are stored in the .hasami/ directory.

Step 2: PR Creation (Automated) #

When changes are merged to main/next branches:

  1. The release-notes.yml GitHub Action runs
  2. It calls hasami publish to update changelogs
  3. It creates a PR titled “Hasami Version Update”

This PR updates all affected changelogs.

Step 3: Tag Creation (Automated) #

When the “Hasami Version Update” PR is merged:

  1. The release-tags.yml GitHub Action is triggered
  2. It identifies that a Hasami Version Update PR was merged
  3. It creates tags in yyyy-mm-dd format using hasami tag
  4. Tags are attached to the main branch

Manual Commands #

Basic Commands #

  • hasami - Start interactive release note creation
  • hasami init - Initialize configuration (creates .hasami/config.toml)
  • hasami publish - Publish all release notes to changelogs
  • hasami version [project-id] - Get current version(s)
  • hasami history [project-id] - View release history
  • hasami add --project ID --type TYPE --bump BUMP "content" - Add release note in one line

Non-Interactive Release Notes #

In addition to the interactive mode, you can create release notes in one command:

# Create a feature release note for webapp (patch bump)
hasami add --project webapp --type feature --bump patch "Added dark mode support"

# Using shorthand options
hasami add -p bonsapi -t bugfix -b patch "Fixed authentication issue"

This is useful for:

  • CI/CD automation
  • Quick changes with simple notes
  • Scripting multiple release notes

Automatic GitHub Integration #

Hasami automatically fetches GitHub information when you run hasami publish:

  1. It connects to GitHub API to find PRs associated with commits
  2. It extracts GitHub usernames and PR numbers
  3. It formats this data as clickable Markdown links in changelogs
## 2023-04-21

### Features

- (minor): Added dark mode support [@johndoe](https://github.com/johndoe) in [#123](https://github.com/tofu2-limited/bonsai/pull/123)

No manual entry of PR numbers or GitHub usernames is required - the system handles this automatically during the publish phase, minimizing developer effort.

Configuration #

The configuration file (.hasami/config.toml) defines:

[global]
tag_format = "yyyy-mm-dd"
repo_url = "https://github.com/tofu2-limited/bonsai"

[[project]]
id = "webapp"
name = "Web Application"
language = "typescript"
package_path = "./apps/webapp/package.json"
# Optional: override global repo_url
repo_url = "https://github.com/tofu2-limited/bonsai-webapp"

# Additional projects...

The repo_url field is essential for accessing the GitHub API and generating correct links.

Release Notes Format #

Release notes use a frontmatter format:

---
scope: webapp  # Project ID
type: feature  # feature, bugfix, misc
bump: minor    # major, minor, patch
github_user: johndoe  # Optional: GitHub username
commit_hash: abc123  # Optional: Commit hash
pr_number: 123  # Optional: Pull request number
---

Added real-time collaboration features to the document editor.

Files are named: YYYYMMDD-projectid-type-bump.md

Integration with GitHub Actions #

Hasami is integrated with two GitHub Actions workflows:

  1. release-notes.yml: Creates PRs with changelog updates
  2. release-tags.yml: Creates release tags when PRs are merged

This automation ensures consistent releases across the monorepo.

The generated changelogs include GitHub information with clickable links when available:

## 2023-04-21

### Features

- (minor): Added dark mode support [@johndoe](https://github.com/johndoe) in [#123](https://github.com/tofu2-limited/bonsai/pull/123)
- (patch): Improved performance

### Bug Fixes

- (patch): Fixed authentication bug [@janedoe](https://github.com/janedoe)

Best Practices #

  • Create release notes as part of your development process, not after
  • Use clear, concise language in release notes
  • Choose the appropriate bump type based on semantic versioning rules
  • Review generated changelogs before approving PRs
  • Don’t manually create tags - let the automation handle it

Troubleshooting #

Common Issues #

  • Conflicts in changelog: Resolve merge conflicts and ensure proper formatting
  • Failed PR creation: Check GitHub Action logs for errors
  • Missing tags: Verify that the PR title exactly matches “Hasami Version Update”