Update README.md to provide a comprehensive overview of The Order monorepo, including repository structure, quickstart guide, development workflow, and contribution guidelines.
This commit is contained in:
defiQUG
235
docs/governance/CONTRIBUTING.md
Normal file
235
docs/governance/CONTRIBUTING.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user