CONTRIBUTING.md

gistfile1.txt

# CONTRIBUTING.md

Welcome to our **create-t3-app** project! This document provides guidelines and best practices to help both human developers and coding agents contribute effectively. It reflects our **Drizzle + SQLite** setup with **Tailwind CSS** and the **Next.js App Router**.

---

## 1. Overview

We use **create-t3-app** with the following core technologies:

- **Next.js App Router** (`src/app`)  
- **TypeScript** for type safety  
- **Drizzle** for database interactions  
- **SQLite** as our local database  
- **Tailwind CSS** for styling  
- **ESLint** and **Prettier** for code formatting and linting  
- **pnpm** as our package manager  

This project uses React Server Components, don't create API end points for passing data between the client and server.

### Folder Structure (App)

Below is the typical scaffold when you choose **Drizzle** and **Tailwind** in create-t3-app. Some entries may vary depending on your environment and custom changes:

```
.
├─ public
│  └─ favicon.ico
├─ src
│  ├─ app
│  │  ├─ layout.tsx
│  │  └─ page.tsx
│  ├─ server
│  │  └─ db
│  │     ├─ index.ts
│  │     └─ schema.ts
│  ├─ styles
│  │  └─ globals.css
│  └─ env.js
├─ .env
├─ .env.example
├─ .eslintrc.cjs
├─ .gitignore
├─ db.sqlite              (created after `pnpm db:push` when using SQLite)
├─ drizzle.config.ts
├─ next-env.d.ts
├─ next.config.mjs        (or next.config.js)
├─ package.json
├─ postcss.config.js
├─ prettier.config.mjs
├─ README.md
├─ tailwind.config.ts
└─ tsconfig.json
```

> **Note:** This project is in a subfolder `app`, remember to navigate there before running any commands.

---

## 2. Getting Started

### Fork & Clone

1. **Fork** the repository on GitHub.
2. **Clone** your fork locally:
   ```bash
   git clone https://github.com/<your-username>/<repo-name>.git
   cd <repo-name>
   ```
3. **Navigate** to the subfolder if applicable (e.g., `cd app`).
4. **Set upstream** for syncing with the original:
   ```bash
   git remote add upstream https://github.com/<original-author>/<repo-name>.git
   ```

### Install Dependencies

We use **pnpm**:

```bash
pnpm install
```

### Development Server

```bash
pnpm db:push
pnpm dev
```
Access the app at [http://localhost:3000](http://localhost:3000).

### Production Build

```bash
pnpm build
pnpm start
```

---

## 3. Adding & Updating Code

### Branching Strategy

1. **main** (or `master`): Production-ready code.  
2. **feature/<name>**: New features or major refactors.  
   - Example: `feature/add-user-profiles`
3. **bugfix/<name>**: Bug fixes.  
   - Example: `bugfix/fix-layout-styling`

### Committing & Pull Requests

We encourage **Conventional Commits**, such as:

```
feat(db): implement new user schema
fix(styles): remove duplicate button CSS
docs(readme): update contributing guidelines
```

When opening a **Pull Request**:

- **Describe** your changes clearly.  
- **Reference** any relevant issues (e.g., `Closes #10`).  
- **Include screenshots** or clips if it’s a UI change.

---

## 4. Project Structure Details

### `public/`

- Contains static assets (e.g., `favicon.ico`).  
- Anything in `public` is served at the root (`/`).

### `src/app/`

- **Next.js App Router**:
  - `layout.tsx` handles layout and providers for your app.
  - `page.tsx` is the primary route (homepage).  
- Add more routes as folders or files in this directory.

### `src/server/`

- **Server-only code**.  
- Typically includes database logic, server APIs, or other backend utilities.

#### `src/server/db/`

- **Drizzle + SQLite** usage:
  - **`index.ts`**: Initializes the Drizzle client.  
  - **`schema.ts`**: Defines database schema (tables, columns, etc.).  
- After configuring `.env`, run:
  ```bash
  pnpm db:push
  ```
  This pushes your schema to the SQLite database (generates `db.sqlite` if not present).

### `src/styles/`

- **Tailwind CSS** global styles (`globals.css`).  
- Modify `tailwind.config.ts` to customize Tailwind further.

### Environment Variables

- `.env` is **not** committed (see `.gitignore`).  
- `.env.example` shows sample keys.  
- For local dev, place secrets in `.env`.  
- Validate or define them in `src/env.js` (or `.ts`) if the T3 template includes environment validation.

---

## 5. Database Workflow

- **Drizzle** requires a `drizzle.config.ts` file at project root for migrations/config.  
- **SQLite**:
  - Your local database is `db.sqlite`.
  - Use `pnpm db:push` to apply schema changes.  
  - For more advanced usage, see [Drizzle documentation](https://orm.drizzle.team/).

---

## 6. Coding Standards

1. **ESLint** + **Prettier**: Code must pass lint checks and auto-format.  
2. **TypeScript**:
   - Use `strict` mode from the generated `tsconfig.json`.  
   - Provide appropriate types for components, functions, etc.
3. **File Naming**:
   - `PascalCase` for React components (`UserProfile.tsx`).  
   - `camelCase` for utility files/functions.  
   - Keep folder names `kebab-case` or `lowerCamelCase`.
4. **Tailwind CSS**:
   - Rely on utility classes in `globals.css` and the configured theme.  
   - `prettier-plugin-tailwindcss` is enabled to sort classes consistently.

---

## 7. Testing

### Unit & Integration Tests

- **Jest** + **React Testing Library**.  
- Place test files in `tests/` or near the code (`__tests__` subfolders).  
- Example command:
  ```bash
  pnpm test
  ```

### End-to-End Tests

- Optional but recommended: **Cypress** or **Playwright**.  
- Typically placed in `tests/e2e/`.

---