[v2] Automated GitHub PR Creation Workflow

[GarthDB]

Overview

Enable automated PR creation directly from the browser using isomorphic-git and GitHub API.

Context

v1 requires manual PR creation (export + manual process). v2 automates the full workflow: clone → edit → commit → push → PR.

Goals

1. Browser-based git operations
2. GitHub OAuth authentication
3. Automated commit and PR creation
4. Proper changeset generation

Tasks

• Set up browser git infrastructure

  • Add isomorphic-git and Lightning FS dependencies
  • Configure IndexedDB storage
  • Implement shallow clone (depth: 10)
  • Add progress indicators for long operations
  • Handle clone caching and sync

• Implement GitHub OAuth Device Flow

  • Register OAuth app with Adobe GitHub org
  • Implement device code request/polling
  • Build authentication UI with clear instructions
  • Store token in sessionStorage (secure)
  • Handle token expiration and refresh
  • Add "remember me" option (localStorage with encryption)

• Build git client wrapper

  • Implement clone with progress tracking
  • Create branch operations
  • Stage and commit changes
  • Push to remote
  • Error handling for all operations
  • Handle merge conflicts detection

• Add sync management

  • Detect stale local clones
  • Auto-sync before operations
  • Handle merge conflicts (show error + guidance)
  • Cache management (clear old clones)
  • Monitor IndexedDB quota usage

• Build changeset generator

  • Determine package affected (@adobe/spectrum-component-api-schemas)
  • Determine version bump type (patch/minor/major)
  • Generate changeset markdown
  • Validate changeset format
  • Support manual changeset editing

• Implement commit message builder

  • Auto-generate conventional commit message
  • Parse change type (feat/fix/refactor)
  • Extract scope from changes
  • Support manual message editing
  • Validate with commitlint rules

• Build PR creation workflow

  • Generate PR title from commit message
  • Generate PR description from changes
  • Create PR via GitHub API (@octokit/rest)
  • Add labels (enhancement, schema)
  • Link related issues
  • Show PR URL and number

• Add diff preview UI

  • Show visual diffs before committing (using diff2html)
  • File-by-file review
  • Expand/collapse sections
  • Highlight schema changes
  • Show validation status per file

• Implement error recovery

  • Handle authentication failures
  • Handle push failures (permissions, conflicts)
  • Handle rate limiting
  • Provide fallback export if git operations fail
  • Clear error messages with action steps

• Add testing

  • Test git operations in multiple browsers
  • Test OAuth flow
  • Test with slow connections
  • Test quota limits
  • Test error scenarios

Success Criteria

• Clone completes in <20 seconds on average connection
• OAuth authentication works smoothly
• PRs created have proper conventional commits and changesets
• Zero data loss (changes preserved if operations fail)
• Clear error messages guide users through issues
• Works in Chrome, Firefox, Safari, Edge

Dependencies

• [Epic] v1 MVP: Basic Mapping Editor Tool #648 (Basic tool)
• isomorphic-git library
• @octokit/rest library
• GitHub OAuth app registration

Estimated Effort

3-4 weeks

Risks & Mitigations

• Risk: Browser storage limits (IndexedDB ~50MB)

  • Mitigation: Repo is ~10MB, monitor usage, clear old clones

• Risk: Merge conflicts

  • Mitigation: Auto-sync before operations, clear error if conflicts exist

• Risk: Slow clones

  • Mitigation: Shallow clone, progress indicators, caching

• Risk: Token security

  • Mitigation: Use sessionStorage by default, never log tokens

Related

• GitHub PR Workflow Design document
• Deployment Architecture Analysis
• RFC [DRAFT RFC] Token Authoring Workflow and Process #625: Token Authoring Workflow