236 lines
4.9 KiB
Markdown
236 lines
4.9 KiB
Markdown
# Contributing to The Order
|
|
|
|
Thank you for your interest in contributing to The Order! This document provides guidelines and instructions for contributing.
|
|
|
|
## Code of Conduct
|
|
|
|
By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
|
|
|
|
## Getting Started
|
|
|
|
1. Fork the repository
|
|
2. Clone your fork: `git clone https://github.com/your-username/the-order.git`
|
|
3. Create a branch: `git checkout -b feature/your-feature-name`
|
|
4. Install dependencies: `pnpm install`
|
|
5. Make your changes
|
|
6. Test your changes: `pnpm test && pnpm lint`
|
|
7. Commit your changes (see [Commit Guidelines](#commit-guidelines))
|
|
8. Push to your fork: `git push origin feature/your-feature-name`
|
|
9. Open a Pull Request
|
|
|
|
## Development Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js >= 18.0.0
|
|
- pnpm >= 8.0.0
|
|
- Docker (for local services)
|
|
- Git
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Start development servers
|
|
pnpm dev
|
|
|
|
# Run tests
|
|
pnpm test
|
|
|
|
# Run linting
|
|
pnpm lint
|
|
|
|
# Type check
|
|
pnpm type-check
|
|
```
|
|
|
|
### Environment Setup
|
|
|
|
1. Copy `.env.example` to `.env.local` in the workspace you're working on
|
|
2. Configure required environment variables
|
|
3. For secrets, use SOPS (see [Security Policy](SECURITY.md))
|
|
|
|
## Commit Guidelines
|
|
|
|
We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:
|
|
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
<body>
|
|
|
|
<footer>
|
|
```
|
|
|
|
### Types
|
|
|
|
- `feat`: New feature
|
|
- `fix`: Bug fix
|
|
- `docs`: Documentation changes
|
|
- `style`: Code style changes (formatting, etc.)
|
|
- `refactor`: Code refactoring
|
|
- `test`: Test additions or changes
|
|
- `chore`: Build process or auxiliary tool changes
|
|
- `perf`: Performance improvements
|
|
- `ci`: CI/CD changes
|
|
- `revert`: Revert a previous commit
|
|
|
|
### Examples
|
|
|
|
```
|
|
feat(auth): add OIDC provider support
|
|
|
|
Implement OAuth2/OIDC flow with support for multiple providers.
|
|
Adds configuration for eIDAS integration.
|
|
|
|
Closes #123
|
|
```
|
|
|
|
```
|
|
fix(intake): resolve OCR parsing issue with PDFs
|
|
|
|
Fixes character encoding problems when processing multi-page PDFs.
|
|
Adds proper error handling for corrupted documents.
|
|
|
|
Fixes #456
|
|
```
|
|
|
|
## Pull Request Process
|
|
|
|
1. **Update Documentation**: Update relevant documentation for your changes
|
|
2. **Add Tests**: Include tests for new features or bug fixes
|
|
3. **Update Changelog**: Add entry to CHANGELOG.md (if applicable)
|
|
4. **Ensure Tests Pass**: All CI checks must pass
|
|
5. **Request Review**: Request review from relevant code owners (see CODEOWNERS)
|
|
|
|
### PR Title Format
|
|
|
|
Use the same format as commit messages:
|
|
|
|
```
|
|
feat(scope): brief description
|
|
```
|
|
|
|
### PR Description Template
|
|
|
|
```markdown
|
|
## Description
|
|
Brief description of changes
|
|
|
|
## Type of Change
|
|
- [ ] Bug fix
|
|
- [ ] New feature
|
|
- [ ] Breaking change
|
|
- [ ] Documentation update
|
|
|
|
## Testing
|
|
How was this tested?
|
|
|
|
## Checklist
|
|
- [ ] Code follows style guidelines
|
|
- [ ] Self-review completed
|
|
- [ ] Comments added for complex code
|
|
- [ ] Documentation updated
|
|
- [ ] Tests added/updated
|
|
- [ ] All tests pass
|
|
- [ ] No new warnings
|
|
```
|
|
|
|
## Code Style
|
|
|
|
### TypeScript
|
|
|
|
- Use strict TypeScript configuration
|
|
- Prefer type over interface for unions/intersections
|
|
- Use explicit return types for public functions
|
|
- Avoid `any` type
|
|
|
|
### Formatting
|
|
|
|
- Use Prettier for code formatting
|
|
- Run `pnpm format` before committing
|
|
- ESLint rules must pass
|
|
|
|
### Naming Conventions
|
|
|
|
- Variables: `camelCase`
|
|
- Functions: `camelCase`
|
|
- Classes: `PascalCase`
|
|
- Constants: `UPPER_SNAKE_CASE`
|
|
- Files: `kebab-case` for utilities, `PascalCase` for components
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
- Write unit tests for all new features
|
|
- Aim for >80% code coverage
|
|
- Use descriptive test names
|
|
- Follow AAA pattern (Arrange, Act, Assert)
|
|
|
|
### Integration Tests
|
|
|
|
- Write integration tests for API endpoints
|
|
- Test error cases and edge cases
|
|
- Use test fixtures from `packages/test-utils`
|
|
|
|
### E2E Tests
|
|
|
|
- E2E tests for critical user flows
|
|
- Use Playwright or similar framework
|
|
- Run in CI/CD pipeline
|
|
|
|
## Documentation
|
|
|
|
### Code Documentation
|
|
|
|
- Document all public APIs
|
|
- Use JSDoc for functions and classes
|
|
- Include examples for complex usage
|
|
|
|
### Architecture Documentation
|
|
|
|
- Update ADRs for significant architectural decisions
|
|
- Document new services in `docs/architecture/`
|
|
- Update data flow diagrams if applicable
|
|
|
|
## Code Review
|
|
|
|
### For Authors
|
|
|
|
- Keep PRs focused and small
|
|
- Respond to feedback promptly
|
|
- Be open to suggestions
|
|
- Update PR based on feedback
|
|
|
|
### For Reviewers
|
|
|
|
- Be constructive and respectful
|
|
- Focus on code, not the person
|
|
- Suggest improvements, don't just point out issues
|
|
- Approve when satisfied
|
|
|
|
## Release Process
|
|
|
|
1. Create release branch from `main`
|
|
2. Update version numbers
|
|
3. Update CHANGELOG.md
|
|
4. Create release PR
|
|
5. After approval, tag release
|
|
6. CI/CD automatically deploys
|
|
|
|
## Questions?
|
|
|
|
- Open an issue for questions
|
|
- Check existing documentation
|
|
- Ask in discussions
|
|
|
|
## Additional Resources
|
|
|
|
- [Architecture Documentation](docs/architecture/README.md)
|
|
- [Security Policy](SECURITY.md)
|
|
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
|