255 lines
6.5 KiB
Markdown
255 lines
6.5 KiB
Markdown
# Monorepo Governance
|
|
|
|
**Last Updated**: 2025-01-27
|
|
**Purpose**: Guidelines for managing monorepositories in the workspace
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This document establishes governance guidelines for creating, managing, and maintaining monorepositories in the workspace.
|
|
|
|
---
|
|
|
|
## Decision Criteria
|
|
|
|
### When to Create a Monorepo
|
|
|
|
Create a monorepo when you have:
|
|
- ✅ **Multiple Related Projects**: Projects that share code, dependencies, or infrastructure
|
|
- ✅ **Shared Code Dependencies**: Common utilities, types, or libraries used across projects
|
|
- ✅ **Coordinated Releases**: Projects that need to be released together
|
|
- ✅ **Common Infrastructure**: Shared infrastructure, tooling, or configuration
|
|
- ✅ **Unified Development Workflow**: Team working across multiple related projects
|
|
|
|
**Do NOT create a monorepo for:**
|
|
- ❌ Unrelated projects with no shared code
|
|
- ❌ Projects with independent release cycles
|
|
- ❌ Projects with different technology stacks (unless using workspaces)
|
|
- ❌ Projects that will be open-sourced independently
|
|
|
|
---
|
|
|
|
## Monorepo Structure
|
|
|
|
### Standard Structure
|
|
|
|
```
|
|
monorepo-name/
|
|
├── .gitmodules # Git submodules (if using submodules)
|
|
├── packages/ # Shared packages
|
|
│ ├── shared/ # Common utilities
|
|
│ ├── types/ # TypeScript types
|
|
│ └── config/ # Configuration
|
|
├── apps/ # Applications
|
|
│ └── [app-name]/
|
|
├── tools/ # Development tools
|
|
│ └── [tool-name]/
|
|
├── docs/ # Monorepo documentation
|
|
├── infrastructure/ # Infrastructure as Code
|
|
├── scripts/ # Monorepo scripts
|
|
├── package.json # Root package.json
|
|
├── pnpm-workspace.yaml # pnpm workspace config
|
|
└── turbo.json # Turborepo config
|
|
```
|
|
|
|
---
|
|
|
|
## Submodules vs Packages
|
|
|
|
### Use Git Submodules When:
|
|
- ✅ External repositories need to be included
|
|
- ✅ Independent versioning is required
|
|
- ✅ Projects are maintained separately
|
|
- ✅ External contributors need access to individual repos
|
|
|
|
### Use Packages (Workspaces) When:
|
|
- ✅ Internal code that should be versioned together
|
|
- ✅ Unified versioning and releases
|
|
- ✅ Shared code that changes frequently
|
|
- ✅ Simplified dependency management
|
|
|
|
### Hybrid Approach
|
|
- Use submodules for external/existing projects
|
|
- Use packages for new shared code
|
|
- Migrate from submodules to packages over time
|
|
|
|
---
|
|
|
|
## Versioning Strategy
|
|
|
|
### Option 1: Independent Versioning
|
|
- Each package/submodule has its own version
|
|
- Useful for submodules
|
|
- Allows independent releases
|
|
|
|
### Option 2: Unified Versioning
|
|
- Single version for entire monorepo
|
|
- All packages versioned together
|
|
- Easier for coordinated releases
|
|
|
|
**Recommendation**: Start with independent, move to unified if needed.
|
|
|
|
---
|
|
|
|
## Package Manager & Tooling
|
|
|
|
### Standard Stack
|
|
- **Package Manager**: pnpm workspaces (recommended) or npm/yarn
|
|
- **Build Tool**: Turborepo (recommended) or Nx
|
|
- **Testing**: Vitest (TS/JS), Foundry (Solidity)
|
|
- **Linting**: ESLint + Prettier
|
|
|
|
### Configuration Files
|
|
- `pnpm-workspace.yaml` - Workspace configuration
|
|
- `turbo.json` - Turborepo pipeline configuration
|
|
- `package.json` - Root package.json with workspace scripts
|
|
|
|
---
|
|
|
|
## Release Process
|
|
|
|
### Release Workflow
|
|
1. **Plan**: Identify packages to release
|
|
2. **Version**: Update version numbers
|
|
3. **Test**: Run all tests
|
|
4. **Build**: Build all packages
|
|
5. **Release**: Publish packages
|
|
6. **Tag**: Create git tags
|
|
7. **Document**: Update changelogs
|
|
|
|
### Release Frequency
|
|
- **Major Releases**: Quarterly or as needed
|
|
- **Minor Releases**: Monthly or as needed
|
|
- **Patch Releases**: As needed for bug fixes
|
|
|
|
---
|
|
|
|
## Code Sharing Guidelines
|
|
|
|
### Shared Packages
|
|
- Create packages for code used by 2+ projects
|
|
- Keep packages focused and single-purpose
|
|
- Document package APIs
|
|
- Version packages independently (if using independent versioning)
|
|
|
|
### Package Dependencies
|
|
- Use workspace protocol (`workspace:*`) for internal dependencies
|
|
- Hoist common dependencies to root
|
|
- Document dependency graph
|
|
- Avoid circular dependencies
|
|
|
|
---
|
|
|
|
## CI/CD Guidelines
|
|
|
|
### Pipeline Stages
|
|
1. **Lint & Format**: Code quality checks
|
|
2. **Type Check**: TypeScript/Solidity type checking
|
|
3. **Test**: Unit and integration tests
|
|
4. **Build**: Compile and build artifacts
|
|
5. **Security Scan**: Dependency and code scanning
|
|
6. **Deploy**: Deployment to environments
|
|
|
|
### Caching Strategy
|
|
- Use Turborepo caching for builds
|
|
- Cache test results
|
|
- Cache dependency installation
|
|
|
|
---
|
|
|
|
## Documentation Requirements
|
|
|
|
### Monorepo-Level Documentation
|
|
- README.md with overview
|
|
- Architecture documentation
|
|
- Development setup guide
|
|
- Contribution guidelines
|
|
- Release process documentation
|
|
|
|
### Package-Level Documentation
|
|
- Each package should have README.md
|
|
- API documentation
|
|
- Usage examples
|
|
- Changelog
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### Development Workflow
|
|
1. Create feature branch
|
|
2. Work on affected packages
|
|
3. Run tests for all packages
|
|
4. Update documentation
|
|
5. Submit PR
|
|
|
|
### Dependency Management
|
|
1. Add dependencies at package level when possible
|
|
2. Hoist common dependencies to root
|
|
3. Keep dependencies up-to-date
|
|
4. Audit dependencies regularly
|
|
|
|
### Testing
|
|
1. Test affected packages
|
|
2. Run integration tests
|
|
3. Check test coverage
|
|
4. Ensure all tests pass before merge
|
|
|
|
### Code Quality
|
|
1. Follow code style guidelines
|
|
2. Use pre-commit hooks
|
|
3. Review code changes
|
|
4. Maintain test coverage
|
|
|
|
---
|
|
|
|
## Migration Strategy
|
|
|
|
### Migrating Existing Projects
|
|
1. Create monorepo structure
|
|
2. Add projects as submodules initially
|
|
3. Extract shared code to packages
|
|
4. Migrate projects to packages (optional)
|
|
5. Update documentation
|
|
|
|
### Adding New Projects
|
|
1. Evaluate if project belongs in existing monorepo
|
|
2. Create new monorepo if needed
|
|
3. Follow standard structure
|
|
4. Update documentation
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Issue**: Build failures
|
|
- **Solution**: Check dependency graph, ensure all dependencies are installed
|
|
|
|
**Issue**: Test failures
|
|
- **Solution**: Run tests in affected packages, check for dependency issues
|
|
|
|
**Issue**: Version conflicts
|
|
- **Solution**: Use workspace protocol, hoist common dependencies
|
|
|
|
**Issue**: Circular dependencies
|
|
- **Solution**: Refactor to break circular dependency, use dependency injection
|
|
|
|
---
|
|
|
|
## Review and Updates
|
|
|
|
This governance document should be reviewed:
|
|
- Quarterly
|
|
- When adding new monorepos
|
|
- When changing monorepo structure
|
|
- Based on team feedback
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-27
|
|
**Next Review**: Q2 2025
|
|
|