cv-site/CONTRIBUTING.md

Contributing to CV Site

First off, thank you for considering contributing to this project! This CV site is a personal project, but contributions are welcome to improve the template, fix bugs, or add features that others might find useful.

Table of Contents

• Code of Conduct
• How Can I Contribute?
  • Reporting Bugs
  • Suggesting Enhancements
  • Pull Requests
• Development Setup
• Style Guidelines
  • Go Code Style
  • HTMX Patterns
  • CSS Style
• Testing
• Commit Messages

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainer.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include as many details as possible:

Bug Report Template:

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Environment:**
- Go version: [e.g., 1.21.5]
- OS: [e.g., macOS 14.0, Ubuntu 22.04]
- Browser (if applicable): [e.g., Chrome 120, Firefox 121]

**Additional context**
Add any other context about the problem here.

Suggesting Enhancements

Enhancement suggestions are welcome! Please create an issue with:

• Clear title describing the enhancement
• Detailed description of the proposed functionality
• Use case explaining why this would be useful
• Implementation ideas (optional) if you have thoughts on how to implement it

Pull Requests

1. Fork the repository and create your branch from main

2. Branch naming convention:

   • feature/description - New features (e.g., feature/add-dark-mode)
   • fix/description - Bug fixes (e.g., fix/pdf-export-fonts)
   • docs/description - Documentation updates (e.g., docs/update-readme)
   • refactor/description - Code refactoring (e.g., refactor/simplify-handlers)

3. Make your changes:

   • Follow the style guidelines
   • Add tests if adding new functionality (see Testing)
   • Update documentation as needed

4. Test your changes:

   • Run make dev to test locally
   • Test PDF export functionality
   • Test both English and Spanish versions
   • Test responsive design on different screen sizes

5. Commit your changes with clear commit messages (see Commit Messages)

6. Push to your fork and submit a pull request to the main branch

7. Pull Request Template:

**Description**
Brief description of what this PR does.

**Type of change**
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

**How Has This Been Tested?**
Describe the tests you ran and how to reproduce them.

**Checklist:**
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have tested the changes locally

Development Setup

Prerequisites

• Go 1.21+ installed
• Git for version control
• Make (optional, but recommended)
• Chrome/Chromium for PDF generation testing

Setup Steps

1. Clone your fork:

   git clone https://github.com/YOUR-USERNAME/cv.git
   cd cv
   

2. Install dependencies:

   go mod download
   

3. Set up environment:

   cp .env.example .env
   # Edit .env if needed
   

4. Run development server:

   make dev
   # Or: GO_ENV=development go run main.go
   

5. Open browser:

   http://localhost:1999
   

Useful Make Commands

• make dev - Run in development mode (hot-reload enabled)
• make build - Build production binary
• make test - Test endpoints (requires server running)
• make clean - Remove build artifacts
• make help - Show all available commands

Style Guidelines

Go Code Style

• Follow standard Go conventions:

  • Use gofmt to format code (runs automatically with most editors)
  • Run go vet to catch common mistakes
  • Use meaningful variable and function names
  • Add comments for exported functions and complex logic

• Code organization:

  • Keep handlers in main.go or separate handler files
  • Use the internal/models package for data structures
  • Keep utilities in appropriate packages

• Error handling:

  // Good
  if err != nil {
      log.Printf("Error loading CV data: %v", err)
      http.Error(w, "Internal server error", http.StatusInternalServerError)
      return
  }
  
  // Avoid silent failures
  // Bad: ignoring errors without logging
  data, _ := loadCV()
  

HTMX Patterns

• Use semantic HTML:

  <!-- Good -->
  <button hx-get="/cv?lang=en" hx-target="#cv-content" hx-swap="innerHTML">
    English
  </button>
  
  <!-- Avoid inline styles when possible -->
  

• Keep HTMX attributes organized:

  • hx-get/post first
  • hx-target second
  • hx-swap third
  • Other attributes follow

• Progressive enhancement:

  • Ensure basic functionality works without JavaScript
  • HTMX should enhance, not be required

CSS Style

• Organization:

  • Group related styles together
  • Use comments to separate sections
  • Keep selectors specific but not overly complex

• Naming:

  • Use semantic class names
  • Prefer descriptive names over abbreviations

• Responsive design:

  • Mobile-first approach
  • Use media queries for larger screens
  • Test on multiple screen sizes

Testing

Current State: This project does not yet have automated tests. This is a known gap.

When adding tests (future):

• Write unit tests for new utility functions
• Add integration tests for HTTP handlers
• Test PDF generation functionality
• Ensure tests pass before submitting PR:

  go test ./...
  

Manual testing requirements:

• Test both language versions (English/Spanish)
• Test PDF export (both server-side and browser print)
• Test responsive design (mobile, tablet, desktop)
• Test in multiple browsers (Chrome, Firefox, Safari)
• Verify console has no errors
• Check network tab for failed requests

Commit Messages

Use clear, descriptive commit messages following this format:

type: brief description

Optional longer description explaining what and why (not how).

Fixes #123

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, no logic change)
• refactor: - Code refactoring
• perf: - Performance improvements
• test: - Adding or updating tests
• chore: - Maintenance tasks, dependency updates

Examples:

feat: add dark mode toggle

Add user preference for dark mode with localStorage persistence.
Respects system preference on first visit.

Fixes #42

fix: correct PDF font rendering in headless Chrome

The custom Quicksand font wasn't loading properly in chromedp.
Updated to wait for fonts to load before PDF generation.

Fixes #38

Questions?

Feel free to open an issue with the question label if you need help or clarification on anything!

Thank You!

Your contributions help make this project better for everyone. Thank you for taking the time to contribute! 🎉