CONTRIBUTING.md

Contributing to CV Analyzer

Thank you for your interest in contributing to CV Analyzer! This document provides guidelines and instructions for contributing to the project.

Table of Contents

• Code of Conduct
• Getting Started
• Development Workflow
• Project Structure
• Coding Standards
• Testing Guidelines
• Submitting Changes
• Feature Requests
• Bug Reports

Code of Conduct

By participating in this project, you agree to:

• Be respectful and inclusive
• Provide constructive feedback
• Focus on what's best for the community
• Show empathy towards other contributors

Getting Started

Prerequisites

1. Node.js 18+ installed
2. GitHub Copilot CLI installed and authenticated
3. Git for version control
4. Code editor (VS Code recommended)

Initial Setup

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/YOUR_USERNAME/copilot-cv-analyzer.git
cd copilot-cv-analyzer

# Add upstream remote
git remote add upstream https://github.com/ORIGINAL_OWNER/copilot-cv-analyzer.git

# Install dependencies
npm install

# Run development server
npm run dev

Development Workflow

1. Create a Branch

# Update your main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/your-feature-name
# or for bug fixes
git checkout -b fix/issue-description

2. Make Changes

• Write clear, concise code
• Follow existing code style
• Add comments for complex logic
• Update documentation if needed

3. Test Your Changes

# Run the development server
npm run dev

# Test in browser at http://localhost:3000

# Build to verify no errors
npm run build

4. Commit Your Changes

# Stage your changes
git add .

# Commit with descriptive message
git commit -m "feat: add support for multiple file formats"

Commit Message Format:

<type>: <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, semicolons, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat: add support for DOCX files
fix: resolve PDF extraction error for large files
docs: update API documentation with examples
refactor: extract validation logic into separate module

5. Push and Create PR

# Push to your fork
git push origin feature/your-feature-name

# Create Pull Request on GitHub
# Fill out the PR template
# Link related issues

Project Structure

Understanding the project structure will help you make contributions:

copilot-cv-analyzer/
├── app/
│   ├── api/analyze/route.ts    # API endpoint - modify for new analysis features
│   ├── page.tsx                # Main page - UI state and logic
│   ├── layout.tsx              # Root layout - metadata and structure
│   └── globals.css             # Global styles - Tailwind directives
│
├── components/
│   ├── FileUpload.tsx          # Upload UI - modify for new file types
│   └── AnalysisResults.tsx     # Results display - modify for new output formats
│
├── lib/
│   └── pdfExtractor.ts         # PDF utilities - add new extraction methods
│
├── types/
│   └── cv.ts                   # Type definitions - update for new data structures
│
├── public/                     # Static assets
│   └── pdf.worker.min.mjs      # PDF.js worker (auto-copied)
│
└── [config files]              # Next.js, TypeScript, Tailwind configs

Coding Standards

TypeScript

• Use TypeScript for all new files
• Define types for props, state, and API responses
• Avoid any type - use specific types or unknown
• Use interfaces for object shapes
• Enable strict mode (already configured)

Example:

// Good
interface UploadProps {
  onFileSelect: (file: File) => void;
  disabled?: boolean;
}

// Avoid
const handleUpload = (data: any) => { ... }

React Components

• Use functional components with hooks
• Destructure props for clarity
• Use meaningful names for variables and functions
• Keep components focused - single responsibility
• Extract reusable logic into custom hooks

Example:

// Good
export function FileUpload({ onFileSelect, disabled = false }: UploadProps) {
  const [isDragging, setIsDragging] = useState(false);
  // ...
}

// Avoid
export default function Component(props: any) {
  // 500 lines of code
}

CSS/Tailwind

• Use Tailwind utilities over custom CSS
• Keep consistent spacing (use Tailwind's spacing scale)
• Responsive design - test mobile and desktop
• Accessible colors - maintain contrast ratios

Example:

// Good
<div className="flex items-center gap-4 p-6 rounded-lg border-2 border-dashed">

// Avoid inline styles
<div style={{ display: 'flex', padding: '24px' }}>

File Organization

• One component per file
• Co-locate related files
• Use index files for cleaner imports (if needed)
• Name files to match component names

components/
├── FileUpload.tsx
├── AnalysisResults.tsx
└── AnalysisSection.tsx    # New component

Testing Guidelines

Manual Testing Checklist

Before submitting a PR, verify:

• Application builds without errors (npm run build)
• Development server runs (npm run dev)
• PDF upload works (drag-drop and click)
• File validation works (size, type)
• Analysis API returns results
• Results display correctly
• Error handling works
• Responsive design (mobile/desktop)
• No console errors or warnings

Test with Different Inputs

• Small CV (<1 page)
• Medium CV (2-3 pages)
• Large CV (>3 pages, near 10MB limit)
• Invalid files (non-PDF, oversized)
• Edge cases (empty PDFs, corrupted files)

Browser Testing

Test in multiple browsers:

• Chrome/Edge (Chromium)
• Firefox
• Safari (if on macOS)

Submitting Changes

Pull Request Guidelines

1. Fill out the PR template completely
2. Link related issues (e.g., "Fixes #123")
3. Describe your changes clearly
4. Add screenshots for UI changes
5. List breaking changes if any
6. Update documentation if needed

PR Title Format

<type>(<scope>): <description>

Examples:
feat(upload): add support for DOCX files
fix(api): handle timeout errors gracefully
docs(readme): add deployment instructions

What Happens Next

1. Automated checks run (if configured)
2. Maintainer review within 1-2 weeks
3. Feedback or approval
4. Merge (usually squash and merge)

Feature Requests

Have an idea for a new feature?

1. Check existing issues - it might already be proposed
2. Open a new issue with the "Feature Request" template
3. Describe the feature clearly
4. Explain the use case - why is it needed?
5. Propose implementation (optional)

Good Feature Requests

• Clear description
• Defined scope
• Real-world use case
• Consideration of edge cases

Bug Reports

Found a bug?

1. Check existing issues - it might already be reported
2. Open a new issue with the "Bug Report" template
3. Describe the bug clearly
4. Provide reproduction steps
5. Include environment details

Bug Report Template

**Description:**
Brief description of the bug

**Steps to Reproduce:**
1. Go to '...'
2. Click on '...'
3. See error

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Environment:**
- OS: Windows 11 / macOS / Linux
- Browser: Chrome 120
- Node.js: v20.10.0
- App version: 1.0.0

**Screenshots:**
If applicable, add screenshots

**Additional Context:**
Any other relevant information

Development Tips

Useful Commands

# Development with Turbopack
npm run dev

# Production build
npm run build
npm start

# Type checking
npx tsc --noEmit

# Format check (if you add prettier)
npx prettier --check .

Debugging

Browser DevTools:

• Console for errors
• Network tab for API calls
• React DevTools for component state

Server-Side Debugging:

// Add console logs in API routes
console.log('Request:', await request.json());
console.log('Analysis result:', analysis);

Common Issues

PDF Worker Error:

Copy-Item -Path "node_modules\pdfjs-dist\build\pdf.worker.min.mjs" -Destination "public\pdf.worker.min.mjs"

Copilot Authentication:

copilot auth status
copilot auth login

Build Errors:

# Clear cache
rm -rf .next
rm -rf node_modules
npm install
npm run build

Areas for Contribution

Looking for where to start? Here are some areas that need help:

Beginner-Friendly

• Documentation improvements
• UI/UX enhancements
• Error message clarity
• Adding examples and tutorials

Intermediate

• New analysis categories
• Additional file format support
• Improved error handling
• Performance optimizations

Advanced

• OCR integration for scanned PDFs
• Multi-language support
• Batch processing
• Export functionality (PDF/Word)
• Custom analysis profiles

Questions?

• General questions: Open a Discussion on GitHub
• Bug reports: Open an Issue
• Feature ideas: Open an Issue with "Feature Request" label
• Security concerns: See SECURITY.md (if available)

Recognition

Contributors will be:

• Listed in the project README
• Mentioned in release notes
• Credited in commits

Thank you for contributing to CV Analyzer! 🎉