# Contributing

How to contribute to StackPatch

## Getting Started

### Setup

1. **Fork the repository** on GitHub  
2. **Clone your fork**:
   
   ```
   git clone https://github.com/your-username/StackPatch.git
   cd StackPatch
   ```

3. **Install dependencies**:
   
   ```
   pnpm install
   ```

4. **Set up git hooks**:
   
   ```
   pnpm prepare
   ```

> **Important:** After adding new dependencies, always run `pnpm install` and commit the updated `pnpm-lock.yaml`. Pre-commit hooks will catch outdated lockfiles.

## Development Workflow

### 1. Create a Branch

Never commit directly to `main`. Always use feature branches:

```
git checkout -b feature/your-feature-name
```

### 2. Make Your Changes

- Write clean, readable code
- Follow existing code style
- Add comments for complex logic
- Update documentation if needed

### 3. Write Tests

All new features need tests. Place them in `__tests__/` directories:

```
# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage
```

### 4. Run Linter

```
pnpm lint
```

### 5. Commit Your Changes

Pre-commit hooks will automatically:

- Lint your code
- Run related tests
- Format with Prettier

If hooks fail, fix the issues and commit again.

### 6. Push and Create PR

```
git push origin feature/your-feature-name
```

Then create a Pull Request on GitHub.

## Adding a New Patch

### 1. Create Patch Directory

Create a new folder in `packages/cli/boilerplate/`:

```
mkdir packages/cli/boilerplate/your-patch-name
```

### 2. Add Boilerplate Files

Add your patch files to the directory:

```
packages/cli/boilerplate/your-patch-name/
├── app/
│   └── your-feature/
│       └── page.tsx
└── components/
    └── your-component.tsx
```

### 3. Register the Patch

Add your patch to the `PATCHES` object in `packages/cli/bin/stackpatch.ts`:

```
const PATCHES: Record<
  string,
  { path: string; dependencies: string[] }
> = {
  // ... existing patches
  "your-patch-name": {
    path: "your-patch-name",
    dependencies: ["package1", "package2"],
  },
};
```

### 4. Add Tests

Create tests in `packages/cli/__tests__/`:

```
describe("your-patch-name", () => {
  it("should add files correctly", () => {
    // Your test
  });
});
```

### 5. Update Documentation

- Add your patch to the documentation in `content/docs/guides.mdx`
- Update any relevant documentation

## Pull Request Guidelines

### Before Submitting

- ✅ All tests pass
- ✅ Code is linted and formatted
- ✅ Documentation is updated
- ✅ Changes are focused and small
- ✅ Commit messages are clear

### PR Description

Include:

- What changes you made
- Why you made them
- How to test the changes
- Screenshots (if UI changes)

### Review Process

- All PRs require review before merging
- CI checks must pass
- Address review comments promptly
- Keep PRs focused and small

## Branch Protection

The `main` branch is protected:

- ✅ All changes via Pull Request
- ✅ Tests must pass
- ✅ No direct commits (except merges)

This is enforced by GitHub Actions and git hooks.

## Code Style

- Use TypeScript for all new code
- Follow existing patterns and conventions
- Keep functions small and focused
- Add JSDoc comments for public APIs
- Use meaningful variable and function names

## Testing

### Writing Tests

- Test happy paths and edge cases
- Use descriptive test names
- Keep tests isolated and independent
- Mock external dependencies

### Running Tests

```
# Run all tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage report
pnpm test:coverage
```

## Questions?

- **GitHub Issues** - Ask questions or report bugs
- **Discussions** - Join the conversation
- **Discord** - Chat with the community

## Thank You!

Your contributions make StackPatch better for everyone. We appreciate your time and effort!