Init commit

CONTRIBUTING.md

@@ -0,0 +1,303 @@
+# Contributing to LinkBeam
+
+Thank you for your interest in contributing to LinkBeam! This document provides guidelines and instructions for development.
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.21 or later
+- Make (optional, for using Makefile commands)
+- golangci-lint (for code quality checks)
+- pre-commit (optional, for automated checks)
+
+### Getting Started
+
+1. Fork and clone the repository:
+
+```bash
+git clone https://github.com/5mdt/linkbeam.git
+cd linkbeam
+```
+
+2. Install dependencies:
+
+```bash
+go mod download
+```
+
+3. Build the project:
+
+```bash
+make build
+# or: go build -o dist/linkbeam cmd/linkbeam/main.go
+```
+
+## Pre-commit Hooks
+
+This project uses pre-commit hooks to ensure code quality. Setting them up is highly recommended.
+
+### Installation
+
+```bash
+# Install pre-commit (if not already installed)
+pip install pre-commit
+# or: brew install pre-commit  (on macOS)
+
+# Install golangci-lint (if not already installed)
+# See: https://golangci-lint.run/usage/install/
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+
+# Install the git hook scripts
+pre-commit install
+# or: make install-hooks
+```
+
+### Running Hooks
+
+```bash
+# Run against all files
+pre-commit run --all-files
+# or: make pre-commit
+
+# Hooks will automatically run on git commit
+git commit -m "your message"
+```
+
+The pre-commit hooks check:
+- Go code formatting (`go fmt`)
+- Import organization (`goimports`)
+- Code quality (`go vet`, `golangci-lint`)
+- Tests (`go test`)
+- Module tidiness (`go mod tidy`)
+- YAML syntax
+- Trailing whitespace
+- End of file fixes
+- And more
+
+**Note**: The pre-commit framework will automatically download required Go tools on first run if they're not already installed.
+
+## Development Commands
+
+### Building
+
+```bash
+# Build binary (outputs to dist/linkbeam)
+make build
+# or: go build -o dist/linkbeam cmd/linkbeam/main.go
+```
+
+### Running
+
+```bash
+# Run with example config
+make run-example
+# or: go run cmd/linkbeam/main.go --config internal/config/testdata/config.yaml
+
+# Run with custom config (long flags)
+./linkbeam --config config.yaml --template templates/base.html --output dist/index.html
+
+# Run with custom config (short flags)
+./linkbeam -c config.yaml -t templates/base.html -o dist/index.html
+```
+
+### Testing
+
+```bash
+# Run all tests
+make test
+# or: go test -v ./...
+
+# Run tests for a specific package
+go test ./internal/config
+go test ./internal/generator
+
+# Run a single test function
+go test -v -run TestLoad ./internal/config
+
+# Run tests with coverage
+go test -cover ./...
+go test -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out
+```
+
+### Code Quality
+
+```bash
+# Format code
+go fmt ./...
+# or: make fmt
+
+# Run go vet
+go vet ./...
+
+# Run golangci-lint
+golangci-lint run
+# or: make vet
+
+# Run all quality checks
+make pre-commit
+```
+
+### Cleaning
+
+```bash
+# Clean build artifacts
+make clean
+```
+
+## Project Structure
+
+```
+linkbeam/
+├── cmd/linkbeam/          # Main application entry point
+│   ├── main.go
+│   └── main_test.go
+├── internal/
+│   ├── config/            # Configuration loading and validation
+│   │   ├── config.go
+│   │   ├── config_test.go
+│   │   └── testdata/
+│   └── generator/         # Site generation and rendering
+│       ├── generator.go
+│       └── generator_test.go
+├── templates/             # HTML templates
+│   └── base.html
+├── themes/                # CSS theme files
+│   ├── light.css
+│   └── dark.css
+├── dist/                  # Build output: binary and generated site (gitignored)
+├── .gitea/                # CI/CD workflows
+│   └── workflows/
+├── Makefile              # Build automation
+├── go.mod                # Go module definition
+└── go.sum                # Go dependencies
+```
+
+## Architecture
+
+### Two-Layer Structure
+
+1. **Config Layer** (`internal/config/`):
+   - Loads and validates YAML configuration files
+   - Defines data structures: `Config`, `Link`, `Social`
+   - Validates theme (must be "light" or "dark") and required fields
+   - Config validation happens automatically during `config.Load()`
+
+2. **Generator Layer** (`internal/generator/`):
+   - **HTML Generation**: Orchestrates template rendering using Go's `html/template`
+     - `GenerateSite(cfg, templatePath, outPath)` - Creates HTML from templates
+   - **Asset Management**: Copies CSS themes and static files to output directory
+     - `CopyAssets(distDir, themeDirs...)` - Copies theme files to dist/themes/
+   - **Text Rendering**: Plain-text representation for debugging
+     - `RenderUserPage(cfg)` - Returns text-based preview of the page
+
+### Testing Strategy
+
+- Tests use table-driven patterns and dependency injection
+- `cmd/linkbeam/main_test.go`: Mocks the config loader and captures stdout
+- Config tests validate YAML parsing and business rules
+- Generator tests verify file creation and template execution
+- All tests use the testdata in `internal/config/testdata/config.yaml`
+
+## Making Changes
+
+### Adding New Features
+
+1. Create a new branch for your feature:
+```bash
+git checkout -b feature/your-feature-name
+```
+
+2. Write tests first (TDD approach recommended)
+3. Implement the feature
+4. Ensure all tests pass: `go test ./...`
+5. Run pre-commit hooks: `pre-commit run --all-files`
+6. Commit your changes with a descriptive message
+
+### Code Style
+
+- Follow standard Go conventions and idioms
+- Use `gofmt` for formatting (handled by pre-commit)
+- Write clear, descriptive variable and function names
+- Add comments for exported functions and types
+- Keep functions focused and concise
+
+### Testing Guidelines
+
+- Write tests for all new functionality
+- Aim for high test coverage
+- Use table-driven tests for multiple test cases
+- Use testdata files for fixtures
+- Test both success and error cases
+
+### Commit Messages
+
+- Use clear, descriptive commit messages
+- Start with a verb in present tense (e.g., "Add", "Fix", "Update")
+- Reference issue numbers when applicable
+- Keep the first line under 72 characters
+
+Examples:
+```
+Add support for custom CSS themes
+Fix avatar path resolution in config loader
+Update template to include meta tags
+```
+
+## CI/CD Pipeline
+
+The project uses Gitea Actions for continuous integration and deployment.
+
+### Workflows
+
+1. **CI Pipeline** (`.gitea/workflows/ci.yml`):
+   - Runs on push to main/develop and pull requests
+   - **Lint**: golangci-lint, go fmt, go vet
+   - **Test**: Run tests with race detection and coverage
+   - **Build**: Multi-platform builds (Linux, Windows, macOS) for multiple architectures
+   - **Docker**: Build multi-arch Docker images
+
+2. **Docker Publish** (`.gitea/workflows/docker-publish.yml`):
+   - Triggered on version tags (v*)
+   - Builds and pushes Docker images to container registry
+   - Multi-architecture: linux/amd64, linux/arm64, linux/arm/v7
+
+3. **Release** (`.gitea/workflows/release.yml`):
+   - Triggered on semver tags (v*.*.*)
+   - Creates releases with binaries for all platforms
+   - Generates SHA256 checksums for verification
+
+### Local Testing with Docker
+
+```bash
+# Test Docker build
+docker build -t linkbeam:test .
+
+# Run Docker container
+docker run -v $(pwd)/config.yaml:/app/config/config.yaml \
+           -v $(pwd)/dist:/app/dist \
+           linkbeam:test
+
+# Test with docker-compose
+docker-compose up
+```
+
+## Submitting Changes
+
+1. Ensure your code passes all tests and checks
+2. Push your branch to your fork
+3. Open a pull request with a clear description of your changes
+4. Wait for CI checks to pass
+5. Respond to any review feedback
+
+## Questions or Issues?
+
+If you have questions or run into issues:
+- Check existing issues on the repository
+- Open a new issue with a clear description
+- Join our community discussions (if available)
+
+## License
+
+By contributing to LinkBeam, you agree that your contributions will be licensed under the GNU General Public License v3.0.