# Contributing Guide

Thank you for your interest in contributing to Deathwatch Roller! This guide will help you get started.

## How to Contribute

### Reporting Bugs

1. Check if the bug already exists in [issues](https://github.com/alexpolo1/dwroller/issues)
2. Create a new issue with:
   - Clear title and description
   - Steps to reproduce
   - Expected vs actual behavior
   - Screenshots if applicable
   - Your environment (Node version, OS)

### Suggesting Features

1. Check [issues](https://github.com/alexpolo1/dwroller/issues) for similar suggestions
2. Create a feature request issue
3. Include use case and expected behavior

### Pull Requests

1. Fork the repository
2. Create a branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Update documentation
6. Commit with descriptive messages
7. Push to your branch
8. Open a pull request

```bash
git checkout -b feature/amazing-feature
npm install
npm run dev
# Make changes
git add .
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature
```

## Development Workflow

### Setting Up Your Environment

```bash
# Clone the repository
git clone https://github.com/alexpolo1/dwroller.git
cd dwroller

# Install dependencies
npm install

# Start development servers
npm run dev
```

### Code Style

We follow these style guidelines:

- **TypeScript**: Use TypeScript for all new code
- **ESLint**: Run `npm run lint` before committing
- **Prettier**: Auto-format with `npm run format`
- **Testing**: Add tests for all new features

### Commit Guidelines

Use conventional commits:

```
feat:      New feature
fix:       Bug fix
docs:      Documentation
style:     Code style changes
refactor:  Code refactoring
test:      Adding tests
chore:      Maintenance tasks
```

## Code Review Process

All PRs go through:

1. **Initial Review**: Automated checks (lint, tests)
2. **Technical Review**: Code quality, design, performance
3. **Documentation**: Are docs updated?
4. **Approval**: Maintainer approval

### Review Checklist

- [ ] Tests pass
- [ ] No lint errors
- [ ] Code follows style guide
- [ ] Documentation updated
- [ ] No security issues
- [ ] Performance considerations

## Documentation

Documentation is in the `docs/` folder:

- `SUMMARY.md` - Table of contents
- `quick-start.md` - Setup guide
- `user-guide.md` - User documentation
- `api.md` - API reference
- `developer-guide.md` - Dev guide

When adding features:
- Update relevant documentation
- Add code examples
- Include usage instructions

## Testing

### Backend Tests

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

### Frontend Tests

```bash
# Run tests
cd frontend
npm test

# Run with coverage
npm run test:coverage
```

### E2E Tests

```bash
# E2E testing (optional)
npm run test:e2e
```

## Code Quality

### Linting

```bash
# Check for issues
npm run lint

# Fix automatically fixable issues
npm run lint:fix
```

### Formatting

```bash
# Format code
npm run format
```

### Building

```bash
# Build for production
npm run build

# Check build
npm run build
```

## Release Process

1. Update `CHANGELOG.md`
2. Bump version in `package.json`
3. Create release branch
4. Tag release
5. Publish to npm (if applicable)

```bash
npm version patch
git push --follow-tags
```

## Performance Guidelines

- Use indexing for database queries
- Implement caching for static data
- Lazy load heavy components
- Optimize bundle size
- Monitor performance metrics

### Before/After Example

```typescript
// ❌ BAD: N+1 query problem
const items = await db.items.findAll();
items.forEach(item => {
  const owner = await db.owners.findOne({ where: { itemId: item.id } });
});

// ✅ GOOD: Use include for eager loading
const items = await db.items.findAll({
  include: [{ model: Owner }]
});
```

## Security Guidelines

- Never commit secrets or credentials
- Use environment variables for sensitive data
- Review third-party dependencies
- Use prepared statements for SQL
- Implement proper authentication

### Secrets Management

```bash
# ✅ GOOD
export SESSION_SECRET=${SESSION_SECRET}

# ❌ BAD - Never do this
SESSION_SECRET="hardcoded-secret"
```

## Accessibility

Make sure your changes:
- Support keyboard navigation
- Include ARIA labels where needed
- Maintain color contrast
- Support screen readers
- Are responsive

## Browser Support

Test on:
- Chrome/Edge (Chromium)
- Firefox
- Safari
- Mobile browsers

## Performance Benchmarks

- Initial load: < 2s
- API response: < 200ms
- Bundle size: < 500kb (gzipped)
- Lighthouse score: > 90

## Community

- [GitHub Issues](https://github.com/alexpolo1/dwroller/issues)
- [Pull Requests](https://github.com/alexpolo1/dwroller/pulls)
- Contributing guidelines: `CONTRIBUTING.md`

## Code of Conduct

- Be respectful
- Welcome newcomers
- Provide constructive feedback
- Focus on the project

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

## Questions?

Open an issue or start a discussion on GitHub.