Skip to content

TEMPLATE_MIGRATION_PLAN.md

Latest commit

 

History

History
336 lines (276 loc) · 13.7 KB

TEMPLATE_MIGRATION_PLAN.md

File metadata and controls

336 lines (276 loc) · 13.7 KB

Template Migration Plan: Update GitHub Action for New c15t-docs Structure

Overview

The c15t-docs repository has been restructured to use a template-based approach. The template is now located at c15t-docs/templates/c15t instead of being the root of the repository. This plan outlines the changes needed to update the GitHub action to work with this new structure.

Current Architecture

Current Flow

  1. GitHub Action calls setupDocsWithScript() which runs pnpm tsx scripts/setup-docs.ts --vercel
  2. setup-docs.ts clones the entire consentdotio/c15t-docs repository
  3. Copies the entire repo to .docs directory
  4. Installs dependencies in .docs
  5. Vercel deploys from .docs

Current Issues

  • The script clones the entire c15t-docs repo but should only extract templates/c15t
  • The template structure has changed, requiring extraction from a subdirectory
  • The template has its own content pulling mechanism (scripts/content/pull.ts) that needs to run

New Architecture

Target Flow (Simplified Approach)

  1. GitHub Action calls setupDocsWithScript() which runs pnpm tsx scripts/setup-docs.ts --vercel
  2. setup-docs.ts clones consentdotio/c15t-docs repository entirely to .docs
  3. Clean up unwanted templates: Remove any templates in .docs/templates/ that aren't c15t
  4. Install workspace dependencies from .docs root (installs packages + template dependencies)
  5. Run template's content pull script (templates/c15t/scripts/content/pull.ts) which:
    • Pulls docs/packages/changelog from c15t/c15t repo
    • Creates .docs/templates/c15t/.c15t/ directory structure
    • Copies content into .c15t/docs/, .c15t/packages/, .c15t/changelog/
  6. Build and deploy from .docs/templates/c15t/ (Vercel working directory)

Why This Is Simpler:

  • No selective file copying needed
  • Clone entire repo once (we need packages anyway)
  • Just remove unwanted templates after clone
  • Workspace structure is already correct
  • Less code, fewer edge cases

Workspace Structure Required

.docs/
  ├── package.json (root workspace config)
  ├── pnpm-workspace.yaml
  ├── packages/ (all packages needed for compilation)
  │   ├── icon-scanner/
  │   ├── mdx-components/
  │   ├── og/
  │   ├── optin/
  │   ├── optin-docs/
  │   ├── optin-flags/
  │   └── optin-icons/
  └── templates/
      └── c15t/ (only this template, not others)
          ├── .c15t/ (created by pull script)
          │   ├── docs/ (pulled from c15t/c15t repo)
          │   ├── packages/ (pulled from c15t/c15t repo)
          │   └── changelog/ (pulled from c15t/c15t repo)
          ├── src/
          ├── scripts/
          └── ... (template files)

Content Flow:

  1. Clone c15t-docs repo → .docs/ (workspace + packages + templates/c15t)
  2. Remove unwanted templates from .docs/templates/
  3. Install workspace dependencies from .docs/ root
  4. Run templates/c15t/scripts/content/pull.ts → pulls content into .docs/templates/c15t/.c15t/
  5. Build and deploy from .docs/templates/c15t/

Required Changes

1. Update c15t/scripts/setup-docs.ts

File: /Users/christopherburns/glados/c/c15t/scripts/setup-docs.ts

Changes Needed:

  • Modify installDocumentationTemplate() function to copy entire repo, then clean up unwanted templates
  • Copy entire cloned repo to .docs (includes root, packages, templates)
  • Remove any templates that aren't c15t from .docs/templates/
  • Install dependencies from .docs root using workspace-aware install
  • After installation, run template's content pull script: cd .docs/templates/c15t && pnpm tsx scripts/content/pull.ts --vercel

Key Code Changes:

// Current (line ~512):
cpSync(FETCH_CONFIG.TEMP_DOCS_DIR, FETCH_CONFIG.DOCS_APP_DIR, {
  recursive: true,
});

// New: Copy entire repo, then remove unwanted templates
function installDocumentationTemplate(
  buildMode: BuildMode,
  branch: GitBranch
): void {
  cleanupDirectory(FETCH_CONFIG.DOCS_APP_DIR, 'existing docs workspace', buildMode, branch);
  
  // Copy entire cloned repository (includes root, packages, templates)
  cpSync(FETCH_CONFIG.TEMP_DOCS_DIR, FETCH_CONFIG.DOCS_APP_DIR, {
    recursive: true,
  });
  
  // Remove any templates that aren't 'c15t'
  const templatesDir = join(FETCH_CONFIG.DOCS_APP_DIR, 'templates');
  if (existsSync(templatesDir)) {
    const templates = readdirSync(templatesDir, { withFileTypes: true });
    for (const template of templates) {
      if (template.isDirectory() && template.name !== 'c15t') {
        const templatePath = join(templatesDir, template.name);
        log(`Removing unwanted template: ${template.name}`);
        rmSync(templatePath, { recursive: true, force: true });
      }
    }
  }
}

2. Update Dependency Installation

File: /Users/christopherburns/glados/c/c15t/scripts/setup-docs.ts

Changes Needed:

  • Update installDocsAppDependencies() to install from .docs root (workspace root)
  • Use pnpm install --frozen-lockfile from .docs directory
  • This will install all workspace dependencies including template and packages
  • The template's dependencies will be resolved via workspace protocol

Key Code Changes:

// Current (line ~594):
executeCommand(
  `cd ${FETCH_CONFIG.DOCS_APP_DIR} && pnpm install --ignore-workspace --frozen-lockfile`,
  'Installing .docs dependencies in isolation',
  buildMode,
  branch
);

// New: Install workspace dependencies
executeCommand(
  `cd ${FETCH_CONFIG.DOCS_APP_DIR} && pnpm install --frozen-lockfile`,
  'Installing workspace dependencies',
  buildMode,
  branch
);

3. Update docs-preview-action/src/steps/setup-docs.ts

File: /Users/christopherburns/glados/c/consent-github-actions/docs-preview-action/src/steps/setup-docs.ts

Changes Needed:

  • Ensure the script path is correct (scripts/setup-docs.ts exists in c15t repo)
  • Verify the script is called with --vercel flag for production builds
  • The script should handle the new workspace structure automatically

Current Implementation: ✅ Already correct - calls pnpm tsx scripts/setup-docs.ts --vercel

4. Update Template Content Pull Integration

File: /Users/christopherburns/glados/c/c15t/scripts/setup-docs.ts

Changes Needed:

  • After installing workspace dependencies, run the template's content pull script
  • This script (templates/c15t/scripts/content/pull.ts) pulls docs/packages/changelog from c15t/c15t repo
  • The script creates .docs/templates/c15t/.c15t/ directory and populates it with content
  • Must run with --vercel flag in production mode to use environment token
  • Run from .docs/templates/c15t directory (script expects to run from template root)

New Function to Add:

function pullTemplateContent(
  buildMode: BuildMode,
  branch: GitBranch
): void {
  const templateDir = join(FETCH_CONFIG.DOCS_APP_DIR, 'templates', 'c15t');
  if (buildMode === 'production') {
    // In production, the template's pull script will use CONSENT_GIT_TOKEN from env
    // This creates .c15t/ directory inside the template with docs/packages/changelog
    executeCommand(
      `cd ${templateDir} && pnpm tsx scripts/content/pull.ts --vercel --branch=${branch}`,
      'Pulling content from c15t repository into .c15t/',
      buildMode,
      branch
    );
  } else {
    // In development, use default branch (main)
    executeCommand(
      `cd ${templateDir} && pnpm tsx scripts/content/pull.ts --branch=${branch}`,
      'Pulling content from c15t repository into .c15t/',
      buildMode,
      branch
    );
  }
}

Result: After this step, .docs/templates/c15t/.c15t/ will contain:

  • .c15t/docs/ - Documentation content from c15t/c15t repo
  • .c15t/packages/ - Package source code from c15t/c15t repo
  • .c15t/changelog/ - Changelog entries from c15t/c15t repo

5. Handle Vercel Working Directory

Consideration: The template's vercel.json specifies:

{
  "installCommand": "cd ../.. && pnpm install --filter c15t-docs",
  "buildCommand": "pnpm build"
}

Options:

  1. Option A (Recommended): Set working_directory to .docs/templates/c15t in GitHub Action

    • Vercel will deploy from template directory
    • Install command will go up two levels to .docs root
    • Workspace dependencies will be resolved correctly

  2. Option B: Keep working_directory as .docs and update vercel.json

    • Would need to modify vercel.json install command
    • Less clean separation

Recommendation: Use Option A - set working directory to .docs/templates/c15t in the GitHub Action workflow.

6. Update Vercel Deployment Configuration

File: /Users/christopherburns/glados/c/c15t/.github/workflows/deploy-docs.yml

Current Configuration:

  • working_directory: .docs (default)
  • framework: nextjs (default)

Changes Needed:

  • Update working_directory to .docs/templates/c15t to deploy from template directory
  • This allows Vercel's install command (cd ../.. && pnpm install --filter c15t-docs) to work correctly
  • The install command will go up two levels from template to .docs root, then install workspace dependencies

Update Required:

# In workflow file, update both preview and production steps:
working_directory: .docs/templates/c15t

Implementation Steps

Step 1: Update setup-docs.ts Template Installation (Simplified)

  • Modify installDocumentationTemplate() to copy entire repo
  • Add cleanup step to remove unwanted templates (keep only c15t)
  • Add import for readdirSync and rmSync if not already present
  • Verify workspace structure is correct after copy

Step 2: Update Dependency Installation

  • Modify installDocsAppDependencies() to install from workspace root
  • Remove --ignore-workspace flag to enable workspace dependency resolution
  • Install from .docs root directory
  • Verify workspace dependencies resolve correctly

Step 3: Add Content Pull Integration

  • Add pullTemplateContent() function
  • Call it after workspace dependency installation
  • Run from .docs/templates/c15t directory
  • Ensure it uses correct branch and production flags

Step 4: Update Vercel Working Directory

  • Update workflow file to set working_directory: .docs/templates/c15t
  • Update both preview and production deployment steps
  • Verify Vercel install command works correctly

Step 5: Testing

  • Test locally with tsx scripts/setup-docs.ts (development mode)
  • Test with tsx scripts/setup-docs.ts --vercel (production mode)
  • Verify .docs workspace structure is correct:
    • Root files present (package.json, pnpm-workspace.yaml)
    • All packages copied
    • Only templates/c15t present (not other templates)
  • Verify workspace dependencies install correctly
  • Verify content is pulled correctly from c15t/c15t into .docs/templates/c15t/.c15t/
  • Verify .c15t/ directory structure is correct (docs/, packages/, changelog/)
  • Test GitHub Action workflow end-to-end
  • Verify Vercel deployment succeeds from .docs/templates/c15t/

Step 6: Documentation Updates

  • Update script comments to reflect new workspace structure
  • Update error messages to reference correct paths
  • Document the three-step process (workspace setup + dependency install + content pull)

File Change Summary

Files to Modify

  1. /Users/christopherburns/glados/c/c15t/scripts/setup-docs.ts

    • Update installDocumentationTemplate() to create workspace structure
    • Update installDocsAppDependencies() to use workspace install
    • Add pullTemplateContent() function
    • Update main() function to call content pull
    • Update documentation/comments

  2. /Users/christopherburns/glados/c/c15t/.github/workflows/deploy-docs.yml

    • Update working_directory to .docs/templates/c15t for both preview and production steps

Files to Review (No Changes Expected)

  1. /Users/christopherburns/glados/c/consent-github-actions/docs-preview-action/src/steps/setup-docs.ts
    • Verify script path is correct
    • Verify flags are passed correctly
    • No changes needed

Testing Checklist

  • Template extraction works correctly
  • Content pull script runs successfully
  • Dependencies install correctly in .docs
  • Template's build scripts work
  • Vercel deployment succeeds
  • Preview deployments work
  • Production deployments work
  • Branch-specific deployments work (main/canary)

Rollback Plan

If issues occur:

  1. Revert changes to setup-docs.ts
  2. The old script structure should still work if template is moved back
  3. Keep a backup of the current working version

Notes

  • Simplified Approach: Clone entire repo, remove unwanted templates, proceed. Much simpler than selective copying.
  • The template uses workspace dependencies (workspace:*) that require the full workspace structure
  • All packages in packages/ are needed for compilation (mdx-components, optin, og, etc.)
  • The template's vercel.json uses installCommand: "cd ../.. && pnpm install --filter c15t-docs" which expects to be in templates/c15t with workspace root two levels up
  • The template's scripts/content/pull.ts pulls content from c15t/c15t repo and creates .c15t/ directory inside the template
  • The template's source.config.ts references ./.c15t/docs - content must be in template directory
  • This is a four-phase setup: clone repo + cleanup templates + dependency installation + content pull
  • The workspace structure must match c15t-docs monorepo structure for dependency resolution to work
  • Currently only c15t template exists, but cleanup handles future templates gracefully
  • Final structure: .docs/templates/c15t/ contains both template code AND .c15t/ content directory