Enhancement: Improve CONTRIBUTING.md with setup scripts and error handling

[Scarmonit]

Problem

The current CONTRIBUTING.md documentation is functional but could be enhanced to reduce friction for contributors:

1. Manual setup steps - Multiple commands need to be run individually
2. Missing error handling guidance - No troubleshooting section
3. Incomplete OAuth setup - Limited guidance for Cloudflare employees on obtaining OAuth credentials
4. No automated setup - Could benefit from setup scripts
5. Missing testing guidance - No information about running tests or test coverage

Proposed Enhancements

1. Add Setup Script

Create scripts/setup.sh to automate initial setup:

#!/bin/bash
# Check prerequisites (node, pnpm, wrangler)
# Copy .dev.vars.example to .dev.vars if not exists
# Guide user through credential setup
# Install dependencies
# Run initial tests

2. Enhance CONTRIBUTING.md

Add sections for:

Testing

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Check test coverage
pnpm test:coverage

Troubleshooting

• Common OAuth errors and fixes
• Port conflicts (8976)
• KV namespace issues
• API token permissions

Development Workflow

• How to add new tools
• Code style guidelines
• PR submission process

3. Improve OAuth Documentation

For Cloudflare employees:

• Link to internal OAuth app creation guide
• Required OAuth scopes
• Callback URL configuration

For external contributors:

• API token permission requirements
• Scope limitations when using API tokens

4. Add Quick Start

# One-command setup (future enhancement)
pnpm run setup:dev

Benefits

• Faster onboarding for new contributors
• Fewer support requests with better troubleshooting docs
• Consistent setup across different environments
• Better testing practices with clear guidance

Implementation Priority

1. High: Add troubleshooting section
2. High: Add testing guidance
3. Medium: Create setup script
4. Medium: Enhance OAuth documentation
5. Low: Automated one-command setup

Files to Update

• apps/workers-builds/CONTRIBUTING.md
• apps/workers-builds/scripts/setup.sh (new)
• apps/workers-builds/package.json (add setup script)

This enhancement would significantly improve the contributor experience and reduce time-to-first-contribution.