docs/CI_CD_PILOT_PROJECTS.md

# 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