Skip to main content
Thank you for your interest in contributing to Philo! This guide outlines our development workflow, commit practices, and code standards.

​
Commit Discipline

We follow a strict commit discipline to maintain a clean, reviewable git history.

​
Commit After Every Discrete Action

Commit immediately after completing each meaningful change:
  • Adding a feature
  • Fixing a bug
  • Refactoring code
  • Updating documentation
  • Adding a test
Do not batch unrelated changes into a single commit. If a task involves multiple steps, commit after each step — not all at the end.

​
Commit Message Format

Use concise, imperative commit messages that describe what the commit does: 
add bucket column reordering
fix off-by-one in timeline view
update task rollover logic
remove unused import in editor

​
Keep Commits Small and Reviewable

Each commit should:
  • Be focused on a single concern
  • Be understandable without additional context
  • Be easy to review and revert if needed

​
Pre-Commit Checks

Before committing, always run:

​
TypeScript Changes

bun run typecheck
bun run fmt
Or use the combined command: 
bun run check

​
Rust Changes

1

Run cargo check periodically

While making changes, run cargo check frequently to catch errors early:
cd src-tauri
cargo check
2

Fix clippy warnings

Before committing, ensure there are no clippy warnings:
cd src-tauri
cargo clippy
3

Verify compilation

Build the Rust code to verify it compiles:
cd src-tauri
cargo build
4

Format code

Format your Rust code:
cd src-tauri
cargo fmt

​
Code Style Guidelines

​
TypeScript

  • Avoid unnecessary types/interfaces — Don’t create types or interfaces if they’re only used once. Inline them instead, especially for function props.
  • Run type-check periodically — After making TypeScript changes, run bun run typecheck to catch errors early.
function Button({ onClick, label }: { onClick: () => void; label: string }) {
  return <button onClick={onClick}>{label}</button>;
}

​
Rust

  • Avoid unnecessary structs/enums/traits — Don’t create these if they’re not shared. Prefer inlining types when used in only one place.
  • Run cargo check frequently — Don’t wait until the end to check for errors.

​
Comments

By default, avoid writing comments. If you must write one, explain “why” — not “what”.
// Delay required for animation frame to complete before DOM update
await new Promise(resolve => setTimeout(resolve, 16));

​
Releases

Philo uses an automated release workflow powered by GitHub Actions.

​
Creating a Release

1

Bump version numbers

Update the version in both:
  • src-tauri/Cargo.toml
  • src-tauri/tauri.conf.json
Cargo.toml
[package]
name = "philo"
version = "0.0.32"  # Increment version
2

Commit and push

Commit the version bump:
git add src-tauri/Cargo.toml src-tauri/tauri.conf.json
git commit -m "bump version to 0.0.32"
git push
3

Create release with gh CLI

Use the GitHub CLI to create a release:
gh release create v0.0.32 --title "Philo v0.0.32" --notes "- Add @ autocomplete dropdown for selecting tasks by ID or title
- Fix task rollover not respecting recurring task schedules
- Improve widget library search performance"
The CI workflow (.github/workflows/release.yml) will automatically build and upload platform binaries (.dmg, .exe, etc.) to the release.

​
Release Notes Guidelines

  • Do not use --draft — Releases must be published immediately
  • Write concise, descriptive bullet points explaining user-facing changes
  • Focus on what changed from the user’s perspective, not implementation details
  • Do not just list version numbers or raw commit messages
- Add @ autocomplete dropdown for selecting tasks by ID or title
- Fix task rollover not respecting recurring task schedules
- Improve widget library search performance

​
Continuous Integration

Philo uses GitHub Actions for automated testing and builds.

​
Frontend CI

Runs on every push/PR affecting frontend code:
  • Installs dependencies with Bun
  • Type-checks TypeScript (bun run build)
  • Checks code formatting (dprint check)

​
Rust CI

Runs on every push/PR affecting Rust code:
  • Installs system dependencies (Linux)
  • Runs cargo check
  • Runs cargo clippy with warnings as errors
  • Runs cargo test

​
Rust Formatting CI

Runs separately to check Rust formatting:
  • Runs cargo fmt --check

​
Release CI

Triggered when a tag matching v* is pushed:
  • Builds for macOS (Apple Silicon and Intel)
  • Builds for Linux (Ubuntu 22.04)
  • Builds for Windows
  • Uploads binaries to the GitHub release

​
Development Workflow

1

Create a feature branch

git checkout -b feature/my-new-feature
2

Make changes and commit frequently

Follow the commit discipline outlined above. Commit after each discrete action.
3

Run checks before pushing

# TypeScript
bun run check

# Rust
cd src-tauri && cargo clippy && cargo fmt
4

Push and create a pull request

git push origin feature/my-new-feature
gh pr create --title "Add feature X" --body "Description of changes"
5

Ensure CI passes

Wait for all CI checks to pass before merging.

​
Getting Help

Development Setup

Set up your local development environment

Building for Production

Learn how to build desktop apps

Build docs developers (and LLMs) love

Get started for freeTalk to us