docs/MONOREPO_GOVERNANCE.md

# 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