# Contributing to Roadcrew

Thank you for your interest in contributing to Roadcrew! We welcome contributions from the community.

## Contributor License Agreement (CLA)

Before submitting a pull request, all contributors must sign our Contributor License Agreement (CLA).

### Why a CLA?

The CLA grants North Star Holdings, LLC the rights to use your contribution in both the open source version (Apache 2.0) and our commercial premium features. You retain copyright to your contributions.

### Signing the CLA

When you submit your first pull request, the CLA Assistant bot will automatically comment with instructions to sign electronically. It only takes a minute!

[View our CLA](./CLA.md)

## How to Contribute

### Reporting Issues

- Check existing issues before creating a new one
- Use the issue templates when available
- Provide clear reproduction steps for bugs
- Include your environment details (OS, Node.js version, Roadcrew version)

### Submitting Pull Requests

1. **Fork the repository** and create your branch from `dev` (not `main`)
2. **Set up pre-commit hooks** (optional but recommended):
   ```bash
   # Option 1: Using npm script (recommended)
   npm run setup-hooks
   
   # Option 2: Manual setup
   pip install pre-commit  # or: brew install pre-commit
   pre-commit install
   pre-commit install --hook-type commit-msg
   ```
3. **Make your changes** with clear, descriptive commit messages
4. **Test your changes** to ensure nothing breaks
5. **Sign the CLA** when prompted by the CLA Assistant bot
6. **Submit your pull request** targeting `dev` branch with a clear description of changes

### Code Guidelines

- Follow existing code style and conventions
- Add tests for new features when applicable
- Update documentation for user-facing changes
- Keep commits focused and atomic

### Pre-commit Hooks (Optional)

We use [pre-commit](https://pre-commit.com/) to automatically validate code quality before commits:

**What it checks:**
- ESLint (TypeScript linting)
- TypeScript type checking (`tsc --noEmit`)
- Conventional commit message format
- YAML/JSON syntax
- Trailing whitespace and line endings
- Large files and merge conflicts

**Setup:**
```bash
# Quick setup (recommended)
npm run setup-hooks

# Or manual setup
pip install pre-commit  # or: brew install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg

# Run manually on all files (optional)
pre-commit run --all-files
```

**Bypass hooks if needed:**
```bash
git commit --no-verify
```

**Note:** Pre-commit hooks are optional but recommended. All checks also run in CI/CD on pull requests.

### Documentation Guidelines

**Temporary vs. Permanent Files:**

When working on features, analysis, or planning, follow these rules for where to put documentation:

**Temporary Work (`.roadcrew/` directory):**
- ✅ Epic planning and analysis notes
- ✅ Issue breakdown drafts
- ✅ Implementation planning documents
- ✅ Root cause analysis drafts
- ✅ Decision logs (before finalizing)
- ✅ Personal research notes
- ✅ Work-in-progress summaries

These files are gitignored and expected to be deleted after the work is complete.

**Permanent Documentation:**
- `memory-bank/requirements/specs/` - Technical specifications
- `memory-bank/requirements/prds/` - Product requirements documents
- `memory-bank/requirements/brds/` - Business requirements documents
- `memory-bank/requirements/source-docs/` - Feature narratives and design docs
- `context/tests/` - Test plans and test documentation
- `docs/` - Reference guides, how-tos, and development guides
- Root directory - Only essential files (README, CHANGELOG, CONTRIBUTING, LICENSE)

**Before Creating Any Documentation File:**
1. Ask: "Will this be needed in 3 months?" → If NO, use `.roadcrew/`
2. Ask: "Is this temporary analysis?" → If YES, use `.roadcrew/`
3. Ask: "Can I add this to an existing doc?" → If YES, update existing rather than create new
4. Ask: "Is this a status report or summary?" → If YES, DON'T CREATE IT (use CHANGELOG instead)

**What NOT to Create:**
- ❌ Status reports or progress summaries
- ❌ "READY" or "COMPLETE" marker files
- ❌ Temporary analysis in root or `context/`
- ❌ Multiple variations of the same document
- ❌ Implementation guides that duplicate existing docs

**Consolidation Over Proliferation:**
- Update `docs/DEVELOPMENT.md` instead of creating new organization docs
- Update `CHANGELOG.md` instead of creating status reports
- Add to existing specs instead of creating new analysis files
- Use `.roadcrew/` for all temporary work

### Questions?

- Open a discussion in GitHub Discussions
- Review existing documentation in `/docs`
- Check out our [Code of Conduct](./CODE_OF_CONDUCT.md)

## License

By contributing to Roadcrew, you agree that your contributions will be licensed under the Apache License 2.0 for the open source components. See [LICENSE](./LICENSE) for details.