Contributing Guidelines

Ways to Contribute

Thank you for your interest in improving GTM Feedback! Whether you’re reporting bugs, suggesting features, or sending a pull request, contributions are welcome.

Report Bugs

Help us identify and fix issues

Request Features

Suggest new functionality

Contribute Code

Submit pull requests

Reporting Bugs

Please open a GitHub issue and include:

Clear title

Describe the bug concisely in the title

Steps to reproduce

Detailed steps showing how to reproduce the issue

Expected vs actual behavior

What you expected to happen vs what actually happened

Environment details

Browser and version
Operating system
Node.js version
pnpm version

Screenshots or error messages

Include screenshots, console errors, or stack traces if applicable

Requesting Features

For feature requests, open a GitHub issue and describe:

Feature request template

The problem: What problem are you trying to solve?
Proposed solution: Your ideas for how to solve it
User benefit: How would this benefit users of the template?
Alternatives: Any alternative solutions you’ve considered

Improving Documentation

Documentation fixes and clarifications are very welcome!

Small Changes
Larger Changes

For small typos or clarifications, use GitHub’s web editor to make changes directly.

For larger documentation updates:

Clone the repository
Make changes to docs in /docs
Test locally if applicable
Open a pull request

Contributing Code

If you’d like to contribute code, please follow the guidelines below.

Prerequisites

Node.js 20+

Required for running the project

pnpm 10+

This repo uses pnpm exclusively

Other package managers (npm, yarn) are not supported.

Local Development Setup

Clone your fork

git clone <your-fork-url>
cd <repo-name>

Install dependencies

pnpm install

Configure environment

Create .env files for the relevant apps:

apps/www/.env
apps/slack-app/.env

Variables are defined in:

apps/www/src/lib/env.server.ts
apps/www/src/lib/env.client.ts
Slack app config files

Set up database

# run database migrations
pnpm db:push

# seed demo data (optional but helpful)
pnpm db:seed

Start development server

pnpm dev

Web app: http://localhost:3000
Slack app: http://localhost:3001

See the Local Setup guide for detailed instructions.

Development Workflow

Making Changes

Create a feature branch

git checkout -b my-feature

Branch from main for your changes.

Make your changes

Write your code following the project’s patterns and conventions.

Test locally

# run linting
pnpm lint

# build to check for errors
pnpm build

# manually test in the browser
pnpm dev

Commit your changes

git commit -m "feat: describe the change clearly"

Use conventional commit format (see below).

Commit Convention

This project uses Conventional Commits:

New feature

git commit -m "feat: add user analytics dashboard"

Bug fix

git commit -m "fix: resolve avatar background in dark mode"

Documentation changes

git commit -m "docs: update setup instructions"

Code refactoring

git commit -m "refactor: simplify feedback query logic"

Adding or updating tests

git commit -m "test: add tests for feedback API"

Maintenance tasks

git commit -m "chore: update dependencies"

The project uses Husky for pre-commit hooks that automatically format code with Biome.

Testing Your Changes

Before submitting a pull request:

Build successfully

pnpm build

Ensure all packages build without errors.

Pass linting

pnpm lint

Fix any linting errors reported by Biome.

Manual testing

Start the dev server and test your changes:

pnpm dev

Test in light and dark modes
Check responsive layouts (mobile, tablet, desktop)
Test the core user flows affected by your changes
Check browser console and server logs for errors

Pre-commit hooks will automatically format your code with Biome.

Pull Request Process

Before Opening a PR

PR Title

Use a clear, action-oriented title following conventional commit style:

fix: resolve avatar background in dark mode
feat: add user analytics dashboard
docs: improve local setup instructions

PR Description

Include in your PR description:

PR description template

## Summary
Brief description of what this PR does

## Changes
- Detailed list of changes
- Another change

## Screenshots (for UI changes)
Before and after screenshots

## Breaking Changes
Any breaking changes or migration notes

## Testing
How to test these changes

What to Include

Summary

Clear description of the changes

Screenshots

Before/after for UI changes

Breaking Changes

Any breaking changes or migrations

Testing Steps

How to test the changes

Code Style

This project uses Biome for linting and formatting.

Biome Configuration

Formatting
Import Organization
Naming Conventions

Indentation: 2 spaces
Semicolons: Required
Trailing commas: Always
Quotes: Double quotes
Line width: 80 characters

Biome automatically organizes imports in this order:

Node.js built-ins
External packages
Internal packages (@feedback/*)
Relative imports

Files: kebab-case (my-component.tsx)
Components: PascalCase (MyComponent)
Functions: camelCase (myFunction)
Constants: SCREAMING_SNAKE_CASE (MY_CONSTANT)

Commands

pnpm format

Husky pre-commit hooks automatically run biome format --write on staged files.

Project Structure

Understanding the codebase structure:

View detailed structure

.
├── apps/
│   ├── www/              # Next.js feedback web app
│   │   ├── src/
│   │   │   ├── app/      # Next.js app router pages
│   │   │   ├── components/  # React components
│   │   │   ├── workflows/   # Workflow DevKit workflows
│   │   │   └── lib/      # Utilities, queries, actions
│   │   └── scripts/      # Seed scripts
│   └── slack-app/        # Slack integration (Bolt + Nitro)
│       └── server/
│           ├── api/      # API routes
│           ├── listeners/  # Slack event listeners
│           └── lib/      # Slack utilities
├── packages/
│   ├── ai/               # Shared AI package
│   │   └── src/
│   │       ├── agents/   # AI SDK agents
│   │       ├── tools/    # Agent tools
│   │       └── embeddings/  # Vector embeddings
│   ├── database/         # Drizzle ORM schema
│   ├── redis/            # Redis helpers
│   └── config/           # Shared configuration
└── README.md

Key Directories

apps/www/src/app

Next.js App Router pages and API routes

apps/www/src/components

React components (UI and feature components)

apps/www/src/workflows

Workflow DevKit background workflows

apps/www/src/lib

Server actions, utilities, and queries

packages/ai

AI agents, tools, and embedding utilities

packages/database

Drizzle ORM schema and database utilities

Development Guidelines

Database Operations

Critical: Use Drizzle Relational Query Builder (RQB) syntax ONLY. Never use db.select() patterns.

import { db } from "@feedback/db";

const feedback = await db.query.feedback.findMany({
  where: (feedback, { eq }) => eq(feedback.status, 'open'),
  with: { user: true, comments: true }
});

See the Database guide for more details.

Server Actions

Always use next-safe-action clients - never create raw server actions.

"use server";

import { authActionClient } from "@/lib/actions/clients/auth";
import { z } from "zod";

const schema = z.object({
  title: z.string().min(1),
});

export const createFeedback = authActionClient
  .metadata({ actionName: "createFeedback", entity: "feedback" })
  .inputSchema(schema)
  .action(async ({ parsedInput, ctx }) => {
    // action logic
  });

Component Patterns

Use shadcn/ui
Path aliases
Data fetching

Use components from src/components/ui/:

import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";

export function MyComponent() {
  return (
    <Card>
      <Button>Click me</Button>
    </Card>
  );
}

Use the @/ path alias consistently:

// good
import { Button } from "@/components/ui/button";
import { db } from "@feedback/db";

// avoid
import { Button } from "../../../components/ui/button";

Use SWR for client-side data fetching:

import useSWR from "swr";

export function MyComponent({ id }: { id: string }) {
  const { data, error, isLoading } = useSWR(
    `/api/feedback/${id}`,
    fetcher
  );
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return <div>{data.title}</div>;
}

Questions & Support

If you’re not sure how best to contribute:

Check Existing Issues

Search for similar issues or pull requests

Open a Discussion

Open a new issue to discuss your idea or question

Thanks for helping improve GTM Feedback!

Local Setup

Get started with local development

Database

Learn about database operations

Workflows

Create background workflows

Get Started

Core Concepts

Deployment

Features

Integrations

Development

​Ways to Contribute

Report Bugs

Request Features

Contribute Code

​Reporting Bugs

​Requesting Features

​Improving Documentation

​Contributing Code

​Prerequisites

Node.js 20+

pnpm 10+

​Local Development Setup

​Development Workflow

​Making Changes

​Commit Convention

​Testing Your Changes

​Pull Request Process

​Before Opening a PR

​PR Title

​PR Description

​What to Include

Summary

Screenshots

Breaking Changes

Testing Steps

​Code Style

​Biome Configuration

​Commands

​Project Structure

​Key Directories

apps/www/src/app

apps/www/src/components

apps/www/src/workflows

apps/www/src/lib

packages/ai

packages/database

​Development Guidelines

​Database Operations

​Server Actions

​Component Patterns

​Questions & Support

Check Existing Issues

Open a Discussion

​Related Documentation

Local Setup

Database

Workflows

Build docs developers (and LLMs) love

Ways to Contribute

Reporting Bugs

Requesting Features

Improving Documentation

Contributing Code

Prerequisites

Local Development Setup

Development Workflow

Making Changes

Commit Convention

Testing Your Changes

Pull Request Process

Before Opening a PR

PR Title

PR Description

What to Include

Code Style

Biome Configuration

Commands

Project Structure

Key Directories

Development Guidelines

Database Operations

Server Actions

Component Patterns

Questions & Support

Related Documentation