Skip to main content

Contributing

Thank you for contributing to Soku! This guide covers the workflow, conventions, and tools for making contributions.

Getting started​

  1. Clone the repository and install dependencies:

    git clone https://github.com/chasegarsee/sokuho.git
    cd sokuho
    pnpm install

  2. Set up your environment — See Quickstart for environment variable configuration.

  3. Run the development server:

    pnpm dev

Branch workflow​

We use GitHub Flow — short-lived feature branches merged into main:

  1. Create a branch from main: 
    git checkout -b feat/my-feature
  2. Make your changes, committing frequently with meaningful messages
  3. Push and open a pull request against main
  4. Address review feedback
  5. Merge via merge commit (not squash or rebase)

Commit conventions​

Follow Conventional Commits format:

<type>(<scope>): <description>

[optional body]

Common types:

  • feat — New feature
  • fix — Bug fix
  • docs — Documentation changes
  • chore — Build, deps, config changes
  • refactor — Code restructuring without behavior change
  • test — Adding or updating tests
  • style — Formatting, whitespace (not CSS)

Examples:

feat(functions): add Snapchat publishing integration
fix(web): resolve session cookie not clearing on logout
docs: update Firestore data model with credit system
chore: upgrade Next.js to 16.0.8

Code quality checks​

Before pushing, ensure your changes pass all quality gates:

pnpm check    # Runs lint + typecheck + test

Individual commands:

CommandDescription
pnpm lintESLint across all packages
pnpm typecheckTypeScript type checking
pnpm testJest tests with coverage
pnpm buildFull build (checks for broken imports)

Husky pre-commit hooks will also run lint and typecheck automatically.

Pull request guidelines​

  • Keep changes small and focused — one feature or fix per PR
  • Update documentation alongside code changes
  • Add tests for new features or bug fixes
  • Include a clear description of what changed and why
  • Link related issues in the PR description

PR checklist​

  • Code compiles without errors (pnpm typecheck)
  • Linting passes (pnpm lint)
  • Tests pass (pnpm test)
  • Documentation updated if needed
  • No secrets or credentials committed

Project structure​

Understanding where to put new code:

LocationPurpose
apps/web/src/app/Next.js App Router pages and API routes
apps/web/src/components/React components (organized by feature)
apps/web/src/hooks/Custom React hooks
apps/web/src/store/Redux Toolkit slices and selectors
apps/web/src/context/React Context providers
apps/web/src/utils/Utility functions
apps/functions/integrations/Social platform integrations (auth, publish, poll)
apps/functions/http/Express API routes and handlers
apps/functions/orchestrators/Publishing orchestration logic
apps/functions/services/Business logic services
apps/functions/shared/Shared utilities (media, logging, AI)
packages/schema/src/Shared Zod schemas
apps/docs/docs/Docusaurus documentation
apps/cypress/e2e/Cypress E2E tests

Documentation​

When making changes, update the relevant documentation in apps/docs/docs/. See Documentation Standards for style guidelines.

Run the docs site locally:

pnpm --filter docs start   # Dev server at http://localhost:3100
pnpm --filter docs build   # Build to verify no broken links

Adding a new social platform integration​

If you're adding support for a new platform, follow this pattern:

  1. Create apps/functions/integrations/<platform>/ with:
    • auth.js — OAuth start and callback handlers
    • post.js — Publishing logic
    • index.js — Exports all functions
  2. Add exports to apps/functions/index.js
  3. Create Cloud Tasks queue: gcloud tasks queues create publish-<platform>
  4. Wire the platform into the orchestrator (orchestrators/publish-orchestrator.js)
  5. Add Zod schemas to packages/schema/src/domain/platform.ts
  6. Update the frontend integration picker
  7. Add documentation in apps/docs/docs/integrations/<platform>.md
  8. Update the sidebar in apps/docs/sidebars.js