Development Workflow #

This document describes the development workflow for the BonsAI platform.

Overview #

The BonsAI project follows a structured development workflow designed to ensure code quality, maintainability, and efficient collaboration among team members.

Repository Structure #

The BonsAI repository is organized as a monorepo containing multiple applications and libraries:

• /apps - Contains standalone applications
• /libs - Contains shared libraries
• /tools - Contains development and build tools
• /docs - Contains documentation

Development Environment Setup #

Using Coder #

BonsAI development is done exclusively through Coder, our cloud development environment. This ensures consistency across the team and eliminates “works on my machine” issues.

For detailed setup instructions, see the Getting Started Guide.

Quick overview:

1. Initial Setup

   • Log in to Coder with your @gotofu.com Google account
   • Add your SSH public key to both Coder and GitHub

2. Create Workspace

   • Go to Workspaces
   • Create a workspace using the dev template
   • Recommended: t3.2xlarge instance with 500GB disk

3. Automatic Setup

   • The workspace automatically installs Docker, mise, zsh, and other tools
   • The bonsai repository is automatically cloned to ~/bonsai
   • Initial setup runs mise install and mise run init
   • This takes 10-15 minutes on first setup

4. Complete Authentication After workspace creation, authenticate with Doppler and Atlas:

   cd ~/bonsai
   mise run doppler-init  # Select NO for browser, paste token manually
   mise run atlas-init    # Select NO for browser, paste token manually
   

5. Start Development

   mise run dev
   

6. Access Development Tools

   Your Coder workspace includes pre-configured tools accessible from the workspace dashboard:

   • App - Main application (port 3000)
   • Swagger Editor - API specification editor
   • API Docs (Internal) - Internal API documentation (port 8001)
   • Internal Docs - This documentation (port 1313)
   • Database - CloudBeaver for database management
   • Docker - Portainer for container management

   External access for testing:

   • Use ngrok to expose services for external testing (e.g., webhook testing)
   • Ngrok is pre-installed in the workspace
   • See Webhooks with ngrok for details

Development Workflow #

Our team uses Linear to manage the full software development lifecycle — from planning to production deployment. Every issue in Linear represents a task, bug, or feature that moves through defined stages.

1️⃣ Picking Up an Issue #

• If an issue is assigned to you and its status is Backlog or Todo, you can start it anytime
• Open the issue in Linear and click “Copy Git Branch Name” (top-right icon)
• Change the issue status to In Progress

2️⃣ Creating Your Branch #

Always branch off from the main branch. Use the copied Linear branch name to keep everything consistent:

git checkout main
git pull
git checkout -b <copied-branch-name>

Example branch name: koki/eng-1234-add-dark-mode

3️⃣ Developing Your Feature #

While developing:

• Write tests for your changes
• Run code quality checks before committing:

  mise run fix    # Auto-fix linting and formatting issues
  mise run ci     # Run all checks (linting, type checking, tests)
  

• Create release notes using Hasami before opening your PR:

  hasami
  

  See the Release Management guide for details

4️⃣ Opening a Pull Request #

1. Push your branch:

   git push -u origin <branch-name>
   

2. Create a draft PR on GitHub

   • Add a clear description of your changes
   • Link the Linear issue (automatically linked if using Linear branch name)
   • Post the PR link to #eng-pr-review on Slack
   • Linear issue status automatically updates to In Review when PR is opened

3. If the issue has a preview label:

   • Pushing a draft PR automatically creates a preview environment on Coder
   • To request CS team review, add the “CS Needs Testing” label to your PR
   • CS team can also add this label from Linear (automatically syncs to GitHub)

5️⃣ Preview Environments #

Preview environments allow the CS team to test and review features before merging:

• Each commit to your PR triggers an automatic rebuild (takes 10–13 minutes)
• Track build progress in Coder’s deployment logs
• Issue status automatically changes to In Review when PR is opened
• To request CS team review, add the “CS Needs Testing” label to your GitHub PR
• Wait until the preview is live before adding the label

Important: Do not add “CS Needs Testing” label until the preview environment is fully deployed and accessible.

See the Preview Environments guide for more details.

6️⃣ Code Review Process #

• Code owners are assigned as reviewers automatically
• CS team reviews via the preview environment (when “CS Needs Testing” label is added)
• Address all comments and ensure CI checks pass
• Keep your branch up to date with main:

  git checkout main
  git pull
  git checkout <your-branch>
  git rebase main
  git push --force-with-lease
  

7️⃣ Review and Merge Flow #

Your issue will move through these stages in Linear:

CS Team Review Process #

When you need CS team to review your PR with preview environment:

1. Request Review: Add the “CS Needs Testing” label to your GitHub PR
   • Alternatively, CS team can add the label in Linear (automatically syncs to GitHub)
2. CS Team Reviews: CS team tests the preview and updates the label to either:
   • “CS Approved”: Feature approved (tofu-tofie bot approves the PR)
   • “CS Needs Fix”: Issues found (tofu-tofie bot requests changes)
3. Address Feedback: If “CS Needs Fix”, make fixes and push new commits
4. Re-request Review: After fixes, change label back to “CS Needs Testing”
5. Merge: Once approved by all reviewers, merge into main using squash merge

Label Synchronization:

• Labels added in Linear automatically sync to GitHub PR
• Labels added in GitHub PR are visible in Linear issue
• tofu-tofie bot automatically approves or requests changes based on CS team labels

8️⃣ Merging Your PR #

Once approved:

1. Ensure all CI checks pass
2. Ensure all review comments are addressed
3. Use squash merge to merge into main
4. Delete your branch after merging
5. Linear automatically updates the issue status to In Dev

9️⃣ Handling Reverts or Hotfixes #

If the status changes to Needs Revert, it means something broke after deployment:

1. Quick revert: Revert the PR through GitHub UI
2. Or create a hotfix:

   git checkout main
   git pull
   git checkout -b <username>/hotfix-<issue-number>-<description>
   

3. Follow the same review and merge process
4. Update the Linear issue with details

Code Quality Standards #

Code quality is maintained through:

• Linting: ESLint for JavaScript/TypeScript, Clippy for Rust
• Formatting: Prettier for JavaScript/TypeScript, rustfmt for Rust
• Type Checking: TypeScript for frontend, Rust’s type system for backend

Common Commands #

# Run all checks (linting, type checking, tests)
mise run ci

# Auto-fix linting and formatting issues
mise run fix

# Just run linters
mise run lint

# Just run formatters
mise run format

Best Practice: Run mise run fix before committing to catch issues early.

Branch Strategy #

The project follows a trunk-based development workflow:

• main: The main branch represents the current state of development
• feature branches: Short-lived branches for individual features or bug fixes (named via Linear)

All feature branches:

• Are created from main
• Use Linear-generated branch names
• Are merged back to main via squash merge
• Are deleted after merging

Release Management #

Releases are managed using Hasami, our custom release management tool:

# Create release notes (do this before opening a PR)
hasami

# Or create release notes in one command
hasami add --project webapp --type feature --bump patch "Added dark mode"

See the Release Management guide for complete details on the release process.