Initial commit: add .gitignore and README
This commit is contained in:
defiQUG
275
CI_CD_PILOT_PROJECTS.md
Normal file
275
CI_CD_PILOT_PROJECTS.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# CI/CD Pilot Projects
|
||||
|
||||
**Date**: 2025-01-27
|
||||
**Purpose**: Guide for selecting and migrating pilot projects to unified CI/CD
|
||||
**Status**: Implementation Guide
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document identifies candidate projects for CI/CD pilot migration and provides step-by-step migration instructions.
|
||||
|
||||
---
|
||||
|
||||
## Pilot Project Selection Criteria
|
||||
|
||||
### Ideal Candidates
|
||||
1. **Active projects** with regular commits
|
||||
2. **TypeScript/Node.js** projects (matches template)
|
||||
3. **Well-tested** projects (have test suites)
|
||||
4. **Medium complexity** (not too simple, not too complex)
|
||||
5. **Team availability** for feedback
|
||||
|
||||
---
|
||||
|
||||
## Recommended Pilot Projects
|
||||
|
||||
### High Priority (Start Here)
|
||||
|
||||
1. **workspace-shared** (New project)
|
||||
- **Why**: New project, clean slate
|
||||
- **Complexity**: Low
|
||||
- **Risk**: Low
|
||||
- **Benefits**: Validates template for monorepo
|
||||
|
||||
2. **dbis_core** (Active project)
|
||||
- **Why**: Core project, high visibility
|
||||
- **Complexity**: Medium
|
||||
- **Risk**: Medium
|
||||
- **Benefits**: Validates for large TypeScript project
|
||||
|
||||
3. **the_order** (Active monorepo)
|
||||
- **Why**: Monorepo structure, good test case
|
||||
- **Complexity**: High
|
||||
- **Risk**: Medium
|
||||
- **Benefits**: Validates monorepo CI/CD patterns
|
||||
|
||||
### Medium Priority
|
||||
|
||||
4. **Sankofa/api** (Backend service)
|
||||
- **Why**: API service, common pattern
|
||||
- **Complexity**: Medium
|
||||
- **Risk**: Low
|
||||
|
||||
5. **no_five** (DeFi project)
|
||||
- **Why**: Different domain, validates template flexibility
|
||||
- **Complexity**: Medium
|
||||
- **Risk**: Medium
|
||||
|
||||
---
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### Step 1: Prepare Project
|
||||
|
||||
1. **Review current CI/CD** (if exists)
|
||||
- Document current workflow
|
||||
- Identify project-specific requirements
|
||||
- Note any custom steps
|
||||
|
||||
2. **Update project structure** (if needed)
|
||||
- Ensure package.json has required scripts
|
||||
- Verify test setup
|
||||
- Check build configuration
|
||||
|
||||
### Step 2: Create Workflow File
|
||||
|
||||
1. **Copy template**: `.github/workflows/ci-pilot-template.yml`
|
||||
2. **Rename**: `ci-<project-name>.yml`
|
||||
3. **Update paths**: Replace `project-name` with actual project path
|
||||
4. **Customize**: Add project-specific steps if needed
|
||||
|
||||
### Step 3: Test Locally
|
||||
|
||||
1. **Install act** (GitHub Actions local runner):
|
||||
```bash
|
||||
brew install act # macOS
|
||||
# or
|
||||
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
|
||||
```
|
||||
|
||||
2. **Test workflow**:
|
||||
```bash
|
||||
act -W .github/workflows/ci-<project-name>.yml
|
||||
```
|
||||
|
||||
### Step 4: Deploy
|
||||
|
||||
1. **Commit workflow file**
|
||||
2. **Push to branch**
|
||||
3. **Monitor first run**
|
||||
4. **Fix any issues**
|
||||
5. **Merge to main**
|
||||
|
||||
### Step 5: Gather Feedback
|
||||
|
||||
1. **Monitor for 1-2 weeks**
|
||||
2. **Collect feedback from team**
|
||||
3. **Document issues and improvements**
|
||||
4. **Refine template**
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Examples
|
||||
|
||||
### Example 1: workspace-shared
|
||||
|
||||
**Workflow**: `.github/workflows/ci-workspace-shared.yml`
|
||||
|
||||
```yaml
|
||||
name: CI - Workspace Shared
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- 'workspace-shared/**'
|
||||
pull_request:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- 'workspace-shared/**'
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
defaults:
|
||||
run:
|
||||
working-directory: ./workspace-shared
|
||||
# ... rest of template
|
||||
```
|
||||
|
||||
### Example 2: dbis_core
|
||||
|
||||
**Workflow**: `.github/workflows/ci-dbis-core.yml`
|
||||
|
||||
```yaml
|
||||
name: CI - DBIS Core
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- 'dbis_core/**'
|
||||
pull_request:
|
||||
branches: [main, develop]
|
||||
paths:
|
||||
- 'dbis_core/**'
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
defaults:
|
||||
run:
|
||||
working-directory: ./dbis_core
|
||||
# ... rest of template
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
### Pre-Migration
|
||||
- [ ] Review current CI/CD (if exists)
|
||||
- [ ] Document project-specific requirements
|
||||
- [ ] Verify project has required scripts (lint, test, build)
|
||||
- [ ] Test scripts locally
|
||||
|
||||
### Migration
|
||||
- [ ] Copy template workflow
|
||||
- [ ] Customize for project
|
||||
- [ ] Test workflow locally (if possible)
|
||||
- [ ] Commit workflow file
|
||||
- [ ] Push to branch
|
||||
- [ ] Monitor first run
|
||||
- [ ] Fix any issues
|
||||
|
||||
### Post-Migration
|
||||
- [ ] Monitor for 1-2 weeks
|
||||
- [ ] Gather team feedback
|
||||
- [ ] Document issues
|
||||
- [ ] Refine template based on feedback
|
||||
- [ ] Update documentation
|
||||
|
||||
---
|
||||
|
||||
## Common Customizations
|
||||
|
||||
### Adding Database Tests
|
||||
|
||||
```yaml
|
||||
test:
|
||||
# ... existing steps
|
||||
- name: Start database
|
||||
run: docker-compose up -d postgres
|
||||
|
||||
- name: Run tests
|
||||
run: pnpm test
|
||||
env:
|
||||
DATABASE_URL: postgresql://user:pass@localhost:5432/testdb
|
||||
```
|
||||
|
||||
### Adding Docker Build
|
||||
|
||||
```yaml
|
||||
build:
|
||||
# ... existing steps
|
||||
- name: Build Docker image
|
||||
run: docker build -t project-name:latest .
|
||||
|
||||
- name: Push to registry
|
||||
if: github.ref == 'refs/heads/main'
|
||||
run: docker push project-name:latest
|
||||
```
|
||||
|
||||
### Adding Deployment
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
needs: [lint, test, build]
|
||||
runs-on: ubuntu-latest
|
||||
if: github.ref == 'refs/heads/main'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Deploy
|
||||
run: ./scripts/deploy.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feedback Collection
|
||||
|
||||
### Questions to Ask
|
||||
|
||||
1. **Workflow execution**:
|
||||
- Are workflows running correctly?
|
||||
- Any failures or errors?
|
||||
- Performance issues?
|
||||
|
||||
2. **Developer experience**:
|
||||
- Is feedback timely?
|
||||
- Are error messages clear?
|
||||
- Any missing checks?
|
||||
|
||||
3. **Template completeness**:
|
||||
- Missing any common steps?
|
||||
- Any unnecessary steps?
|
||||
- Suggestions for improvements?
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Select 3-5 pilot projects**
|
||||
2. **Migrate first project** (workspace-shared recommended)
|
||||
3. **Monitor and gather feedback**
|
||||
4. **Refine template**
|
||||
5. **Migrate remaining pilots**
|
||||
6. **Roll out to all projects**
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
Reference in New Issue
Block a user