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)
|
||||
|
||||
105
docs/governance/SECURITY.md
Normal file
105
docs/governance/SECURITY.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
We currently support the following versions with security updates:
|
||||
|
||||
| Version | Supported |
|
||||
| ------- | ------------------ |
|
||||
| 1.0.x | :white_check_mark: |
|
||||
| < 1.0 | :x: |
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
We take security vulnerabilities seriously. If you discover a security vulnerability, please follow these steps:
|
||||
|
||||
1. **Do NOT** open a public GitHub issue
|
||||
2. Email security details to: security@the-order.org (or your security contact)
|
||||
3. Include:
|
||||
- Description of the vulnerability
|
||||
- Steps to reproduce
|
||||
- Potential impact
|
||||
- Suggested fix (if any)
|
||||
|
||||
### Response Timeline
|
||||
|
||||
- **Initial Response**: Within 48 hours
|
||||
- **Status Update**: Within 7 days
|
||||
- **Fix Timeline**: Depends on severity (see below)
|
||||
|
||||
### Severity Levels
|
||||
|
||||
- **Critical**: Remote code execution, authentication bypass, data breach
|
||||
- Fix timeline: 24-48 hours
|
||||
- **High**: Privilege escalation, sensitive data exposure
|
||||
- Fix timeline: 7 days
|
||||
- **Medium**: Information disclosure, denial of service
|
||||
- Fix timeline: 30 days
|
||||
- **Low**: Best practices, defense in depth
|
||||
- Fix timeline: Next release cycle
|
||||
|
||||
## Security Practices
|
||||
|
||||
### Secrets Management
|
||||
|
||||
- All secrets must be encrypted using SOPS
|
||||
- Never commit plaintext secrets
|
||||
- Use environment variables for configuration
|
||||
- Rotate secrets regularly
|
||||
- Use short-lived tokens via OIDC
|
||||
|
||||
### Code Security
|
||||
|
||||
- All code must pass security linting (ESLint security plugins)
|
||||
- Dependencies are scanned for vulnerabilities (Grype)
|
||||
- Container images are signed (Cosign)
|
||||
- SBOM generation for all artifacts (Syft)
|
||||
|
||||
### Infrastructure Security
|
||||
|
||||
- Immutable infrastructure via Terraform
|
||||
- Secrets stored in KMS/HSM
|
||||
- Network policies enforced via Kubernetes
|
||||
- API gateway with WAF rules
|
||||
- Regular security audits and penetration testing
|
||||
|
||||
### Access Control
|
||||
|
||||
- Least privilege principle
|
||||
- Quarterly access reviews
|
||||
- MFA required for all production access
|
||||
- Audit logs for all sensitive operations
|
||||
|
||||
### Compliance
|
||||
|
||||
- eIDAS compliance for identity services
|
||||
- Data retention policies per jurisdiction
|
||||
- WORM storage for legal documents
|
||||
- Audit trails for all financial transactions
|
||||
|
||||
## Security Updates
|
||||
|
||||
Security updates are released as:
|
||||
- **Hotfixes**: For critical vulnerabilities
|
||||
- **Patch releases**: For high/medium severity issues
|
||||
- **Regular releases**: For low severity and general improvements
|
||||
|
||||
## Disclosure Policy
|
||||
|
||||
- Vulnerabilities are disclosed after a fix is available
|
||||
- Coordinated disclosure with responsible parties
|
||||
- CVE assignment for eligible vulnerabilities
|
||||
- Security advisories published in `docs/governance/security-advisories/`
|
||||
|
||||
## Contact
|
||||
|
||||
- **Security Email**: security@the-order.org
|
||||
- **PGP Key**: [Link to public key]
|
||||
- **Security Team**: @the-order/security-team
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Threat Models](docs/architecture/threat-models/)
|
||||
- [Incident Response Runbook](docs/governance/runbooks/incident-response.md)
|
||||
- [Security Checklist](docs/governance/security-checklist.md)
|
||||
|
||||
Reference in New Issue
Block a user