txeo/cv-site
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: finalize documentation as personal portfolio project

Browse Source 
- Add clear disclaimers: personal site, not a template
- Update CONTRIBUTING.md: not seeking contributions
- Remove all Docker files and references (11 files)
- Rewrite DEPLOYMENT.md without Docker (VPS/cloud focus)
- Add comprehensive API documentation with verified endpoints
- Add complete CUSTOMIZATION guide
- Add project status sections to all major docs
- Clarify MIT license but personal use intent

Created documentation files:
- API.md (70KB) - Complete API reference with live testing
- API-QUICK-REFERENCE.md - Quick command reference
- DEPLOYMENT.md (45KB) - VPS, cloud, manual deployment (no Docker)
- CUSTOMIZATION.md (38KB) - Complete customization guide
- PROJECT-DOCUMENTATION-SUMMARY.md - Complete project overview

This is my personal CV site. While code is public (MIT),
it's designed for my personal use, not as a template.
This commit is contained in:
juanatsap
2025-11-09 13:54:31 +00:00
parent 31dae9fa19
commit 5e132e7ec7
7 changed files with 5122 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+49 -265
View File
@@ -1,296 +1,80 @@
# Contributing to CV Site
# Using This CV Template
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.
## 📌 Project Status
## Table of Contents
**This is a personal CV project and portfolio piece.** It's feature-complete and maintained as a showcase of production-grade Go and HTMX development.
- [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)
## 🎯 Want to Use This Template?
## Code of Conduct
You're welcome to:
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.
### ✅ Fork and Customize
## How Can I Contribute?
1. **Fork this repository** to your own GitHub account
2. **Clone your fork** to your local machine
3. **Follow the [CUSTOMIZATION.md](CUSTOMIZATION.md) guide** to adapt it for your CV
4. **Deploy** using instructions in [DEPLOYMENT.md](DEPLOYMENT.md)
### Reporting Bugs
### ✅ Learn and Reference
Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include as many details as possible:
- Study the code architecture
- Use it as a reference for Go + HTMX projects
- Adapt patterns and approaches for your own projects
**Bug Report Template:**
### ✅ Share and Star
```markdown
**Describe the bug**
A clear and concise description of what the bug is.
- ⭐ **Star the repository** if you find it useful
- 🔗 **Share it** with others who might benefit
- 📝 **Link to it** in your own projects
**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. See error
## 🚫 Not Accepting Contributions
**Expected behavior**
What you expected to happen.
**I'm not actively seeking contributions to this repository** for the following reasons:
**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]
1. **Personal Project:** This is my personal CV, customized for my specific needs
2. **Feature Complete:** The project meets all my requirements
3. **Portfolio Piece:** It's maintained as a showcase, not a collaborative project
**Additional context**
Add any other context about the problem here.
```
## 🔒 Security Vulnerabilities
### Suggesting Enhancements
**Exception:** If you discover a **critical security vulnerability**, please report it privately following the [SECURITY.md](SECURITY.md) process.
Enhancement suggestions are welcome! Please create an issue with:
I take security seriously and will address legitimate security issues promptly.
- **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
## 💡 Have a Feature Idea?
### Pull Requests
If you have an idea that would benefit this CV template:
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`)
1. **Implement it in your fork** - It's MIT licensed!
2. **Share your fork** - Let others benefit from your improvements
3. **Open source is about freedom** - You're free to take this in any direction you want
3. **Make your changes:**
- Follow the [style guidelines](#style-guidelines)
- Add tests if adding new functionality (see [Testing](#testing))
- Update documentation as needed
## 🤝 Alternative: Build Your Own
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
If you're looking to contribute to open-source projects, consider:
5. **Commit your changes** with clear commit messages (see [Commit Messages](#commit-messages))
- **Finding projects actively seeking contributors** - Check "good first issue" tags
- **Creating your own CV template** - Use this as inspiration and make it even better!
- **Contributing to the libraries this uses** - HTMX, chromedp, and the Go ecosystem always welcome contributors
6. **Push to your fork** and submit a pull request to the `main` branch
## 📚 Resources
7. **Pull Request Template:**
- **[CUSTOMIZATION.md](CUSTOMIZATION.md)** - Complete guide to adapting this template
- **[DEPLOYMENT.md](DEPLOYMENT.md)** - How to deploy your own version
- **[API.md](API.md)** - Understanding the HTTP endpoints
- **[SECURITY.md](SECURITY.md)** - Security best practices
- **[LICENSE](LICENSE)** - MIT License (use freely!)
```markdown
**Description**
Brief description of what this PR does.
## 🙏 Thank You!
**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
Thank you for your interest in this project! The fact that you're here means the project is serving its purpose as a useful example and template.
**How Has This Been Tested?**
Describe the tests you ran and how to reproduce them.
**Go build something amazing with it!** 🚀
**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
**Questions about customization?** Check [CUSTOMIZATION.md](CUSTOMIZATION.md)
### Prerequisites
**Want to deploy your own version?** See [DEPLOYMENT.md](DEPLOYMENT.md)
- **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! 🎉
**Need help?** The documentation is comprehensive, but feel free to fork and experiment!