Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
289 lines (207 loc) · 9.26 KB

CONTRIBUTING.md

File metadata and controls

289 lines (207 loc) · 9.26 KB

Toggo

Contributing

Found a bug? Open an issue. Noticed documentation is out out of date? Update it. See a rough edge in the dev experience? Smooth it out.

Take ownership. Make it better. Ship it.

Version Control (Git)

We use Conventional Commits for PRs.

Examples:

feat: add user profile page
fix: resolve login redirect issue
docs: update README setup instructions
chore: upgrade dependencies

Important

Keep PRs small and focused. Split large features into smaller PRs that are easy to review. This helps:

  • Maintain clear thought process
  • Ship features incrementally
  • Allow reviewers to focus on details

Prerequisites

General

Tool Description Installation
Docker Containerization docker.com
Doppler Secrets management doppler.com/docs/install-cli
Figma Design tool figma.com
Just CLI tool build with Rust Just

Tip

macOS users: Use OrbStack instead of Docker Desktop — it's lighter and faster.

Backend

Tool Description Installation
Go Backend language go.dev/dl
PostgreSQL 15 Database postgresql.org
psql CLI to interact with a PostgreSQL database install psql
Goose Database migrations go install github.com/pressly/goose/v3/cmd/goose@latest
golangci-lint Go linter golangci-lint.run
goimports Formats code + manages imports go install golang.org/x/tools/cmd/goimports@latest
Swag CLI Generate API doc go install github.com/swaggo/swag/cmd/swag@latest
LocalStack Run AWS services locally install cli
Temporal Run workflow orchestration install cli

Useful Go resources:

Frontend

Tool Description Installation
Bun JavaScript runtime & package manager bun.sh
Xcode iOS simulator (macOS only) App Store
Expo Go Run app on physical device iOS / Android
TestFlight iOS beta testing (later) App Store

Note

If you're not on macOS, you can test the app on your physical phone using the Expo Go app.

Doppler Setup

Doppler manages our environment variables. The token will expire once in a while for security reason, so you will need to do this process again.

# 1. Install Doppler CLI
brew install dopplerhq/cli/doppler  # macOS
# See https://docs.doppler.com/docs/install-cli for other OS

# 2. Login to Doppler
doppler login

# 3. Select the workspace (follow the prompts)
doppler setup

When prompted, select:

  • Project: backend
  • Config: dev (for local development)

Running Commands

We use a justfile to run both frontend and backend commands from any directory at high speed. You can view all available commands with:

just

Database & Migrations

Connecting to Database

Ensure your database is up in the Docker Container by:

just dev-be # will start both server and database OR
just up-db # just start the database in container

Then you can go into PSQL and execute any SQL query

# Local database
just connect-db

# Production database
just connect-prod-db
# will turn off local database
just down-db

Note

Can't connect to the database? Usually a port conflict or conflicting Postgres installations.

1. Check what's using port 5432:

lsof -i :5432

2. Check for running Postgres instances:

ps aux | grep postgres

3. Common fixes:

  • Stop Homebrew Postgres: brew services stop postgresql or brew services stop postgresql@15
  • Stop system Postgres (Linux): sudo systemctl stop postgresql
  • Kill a specific process: kill <PID> (use the PID from above)
  • Remove old socket files: rm /tmp/.s.PGSQL.5432 (if you see "socket file" errors)

Running Migrations

Action Local Production
Create migration just migrate-create name=<informative-name> —
Migrate up just migrate-up just migrate-up-prod
Migrate down just migrate-down just migrate-down-prod

Caution

Always run migrations locally and ensure it works correctly first, then open a PR, get it reviewed and merged, then apply to production.

Starting Server

Backend

Ensure you have your Docker app running first.

cd backend
go mod download
just dev-be

To verify the server is running, visit Healthcheck at http://localhost:8000/healthcheck or API doc at http://localhost:8000/docs

Frontend

cd frontend
bun install
just dev-fe
# you can do also `just ios-fe` to start iOS simulator on MacOS

API Documentation

To generate API calls on frontend side and keep our API documentation up-to-date, we will need to add comments above the controllers

// @Summary Healthcheck endpoint
// @Description Returns OK if the server is running
// @Tags example
// @Produce json
// @Success 200 {string} string "ok"
// @Router /healthcheck [get]
func HealthcheckHandler(c *fiber.Ctx) error {
	return c.JSON(fiber.Map{
		"status": "ok",
	})
}

Then, we can generate the swagger.yaml file with:

just api-doc

You can now start the server and your documentation changes should reflect on the route http://localhost:8000/docs

LocalStack Environment

# create a local AWS environment
just localstack-up

# remove local AWS environment
just localstack-down

Mocking (mockery)

We use mockery v3 to auto-generate test mocks from Go interfaces.

Installation

# macOS (Homebrew)
brew install mockery

# Go install (any OS)
go install github.com/vektra/mockery/v3@v3.6.4

For other installation methods see the official docs.

Configuration

Mock generation is configured in backend/.mockery.yml. Each interface you want mocked must be listed there under its package path. For example:

packages:
  toggo/internal/services:
    interfaces:
      FileServiceInterface:
      SearchServiceInterface:
  toggo/internal/repository:
    interfaces:
      ImageRepository:
      SearchRepository:

Generating mocks

cd backend
mockery

Mocks are written to backend/internal/tests/mocks/ and committed to the repository.

Important

Never edit generated mock files by hand. Add the interface to .mockery.yml and re-run mockery instead.

Testing

just test-be