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](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
  - [Reporting Bugs](#reporting-bugs)
  - [Suggesting Enhancements](#suggesting-enhancements)
  - [Pull Requests](#pull-requests)
- [Development Setup](#development-setup)
- [Style Guidelines](#style-guidelines)
  - [Go Code Style](#go-code-style)
  - [HTMX Patterns](#htmx-patterns)
  - [CSS Style](#css-style)
- [Testing](#testing)
- [Commit Messages](#commit-messages)

## Code of Conduct

This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). 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:**

```markdown
**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](#style-guidelines)
   - Add tests if adding new functionality (see [Testing](#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](#commit-messages))

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

7. **Pull Request Template:**

```markdown
**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:**
   ```bash
   git clone https://github.com/YOUR-USERNAME/cv.git
   cd cv
   ```

2. **Install dependencies:**
   ```bash
   go mod download
   ```

3. **Set up environment:**
   ```bash
   cp .env.example .env
   # Edit .env if needed
   ```

4. **Run development server:**
   ```bash
   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:**
  ```go
  // 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:**
  ```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:
  ```bash
  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! 🎉