dwroller/docs/contributing.md

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
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 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

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

# 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

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Frontend Tests

# Run tests
cd frontend
npm test

# Run with coverage
npm run test:coverage

E2E Tests

# E2E testing (optional)
npm run test:e2e

Code Quality

Linting

# Check for issues
npm run lint

# Fix automatically fixable issues
npm run lint:fix

Formatting

# Format code
npm run format

Building

# 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)

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

// ❌ 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

# ✅ 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
• Pull Requests
• 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.