Contributing Guidelines

Getting Started

When contributing to this project, please first discuss the change you wish to make via issue, email, or any other method with the maintainers before making any changes. This helps us:

Guide you through the development process
Provide early feedback on your approach
Avoid duplicate work
Ensure alignment with project goals

Please note we have a Code of Conduct. Please follow it in all your interactions with the project.

Ways to Contribute

🐛 Bug Reports

Use the GitHub issue tracker to report bugs
Include detailed steps to reproduce the issue
Provide system information (OS, Go version, etc.)
Include relevant logs or error messages

💡 Feature Requests

Check the roadmap to see if it's already planned
Open an issue to discuss new feature ideas
Provide clear use cases and benefits
Consider the scope and complexity

📝 Documentation

Fix typos and improve clarity
Add missing documentation
Update outdated information
Translate documentation (future)

🔧 Code Contributions

Fix bugs and implement features
Improve performance and reliability
Add tests and improve test coverage
Refactor and clean up code

Development Setup

Prerequisites

Go 1.25 or later
PostgreSQL 18 or later
ClickHouse 25.8 or later
Node.js 20+ (for frontend)
pnpm package manager
Docker and Docker Compose (optional)
Task for build automation

Installing Task

# macOS (Homebrew)
brew install go-task

# Linux/Windows
go install github.com/go-task/task/v3/cmd/task@latest

# Or download from https://taskfile.dev/installation/

Local Development

Fork and clone the repository

git clone https://github.com/your-username/pingplop.git
cd pingplop

Set up the development environment

# Prepare development environment (installs deps, generates configs)
task prepare

# Start databases with Docker Compose
task compose:up

Run database migrations
```
task migrate:up
```

Start the development server

# Main application with UI (hot reload)
task dev-app

# Status pages application (in another terminal)
task dev-pages

# Or run components separately:
task run-app      # Backend only
task run-ui       # Frontend only

Available Commands

Development

task dev-app          # Start main app with hot reload
task dev-pages        # Start status pages with hot reload
task run-app          # Run main application
task run-worker       # Run regional worker
task run-agent        # Run monitoring agent
task run-pages        # Run status pages
task run-ui           # Run frontend only

Building

task build            # Build all binaries
task build-ui         # Build frontend assets
task docker:build     # Build Docker images

Database

task migrate:up       # Apply migrations
task migrate:down     # Revert last migration
task migrate:status   # Check migration status
task migrate:create   # Create new migration

Testing & Quality

task test:all         # Run all tests
task test:go          # Run Go tests only
task test:coverage-go # Check Go test coverage
task lint             # Run linters
task format           # Format code
task check            # Run static analysis

Docker Compose

task compose:up       # Start services
task compose:down     # Stop services
task compose:logs     # View logs
task compose:status   # Show service status
task compose:rebuild  # Rebuild and restart

Development Workflow

1. Branch Naming

Use descriptive branch names following this pattern:

feature/feature-name - New features
fix/bug-description - Bug fixes
docs/update-description - Documentation updates
refactor/component-name - Code refactoring

2. Commit Messages

Follow the Conventional Commits specification:

type(scope): description

[optional body]

[optional footer]

Examples:

feat(auth): add multi-factor authentication support

fix(monitor): resolve SSL certificate validation issue

docs(api): update authentication endpoint documentation

refactor(database): optimize monitor query performance

Types:

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

3. Pull Request Process

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Write clean, readable code
- Follow existing code style and conventions
- Add tests for new functionality
- Update documentation as needed

Test your changes

# Run all tests
task test:all

# Run linting
task lint

# Check code formatting
task format

# Run static analysis
task check

Commit and push

git add .
git commit -m "feat(scope): your descriptive commit message"
git push origin feature/your-feature-name

Create a Pull Request
- Use a clear, descriptive title
- Reference related issues (e.g., "Closes #123")
- Provide detailed description of changes
- Include screenshots for UI changes
- Ensure all CI checks pass

Code Standards

Go Code Style

Follow standard Go conventions and best practices
Use gofmt for code formatting (automated with task format)
Run golangci-lint and address warnings (automated with task lint)
Write meaningful variable and function names
Add comments for exported functions and complex logic

Frontend Code Style

Use TypeScript for new React components
Follow React best practices and hooks patterns
Use Biome for linting and formatting
Write unit tests for components

Database

Follow the established schema naming conventions
Write migrations for schema changes
Include both up and down migrations
Test migrations thoroughly using task migrate:* commands

Testing

Backend Testing

# Run all Go tests
task test:go

# Run tests with coverage
task test:coverage-go

# Run specific package tests
task test:go -- ./pkg/...

Frontend Testing

The frontend uses modern testing tools integrated with the monorepo structure:

# Frontend tests are included in:
task test:all         # Runs all tests including frontend
pnpm test            # Run frontend tests directly

Project Structure

pingplop/
├── cmd/                 # Application entry points
│   ├── pingplop/       # Main application
│   ├── ping-worker/    # Regional worker
│   ├── ping-agent/     # Monitoring agent
│   └── ping-pages/     # Status pages
├── internal/           # Private application code
├── pkg/                # Public libraries
├── packages/           # Frontend applications
├── config/             # Configuration files
├── database/           # Database migrations and schemas
├── tasks/              # Taskfile task definitions
└── Taskfile.yaml       # Main task configuration

Documentation

Update relevant documentation for new features
Include code examples where appropriate
Use clear, concise language
Follow existing documentation structure
Generate API docs with task generate-swagger

Getting Help

GitHub Discussions: Use for longer-form questions and ideas
GitHub Issues: For bug reports and feature requests
Email: Contact the maintainers at dev@pingplop.com

Recognition

Contributors will be recognized in:

Project README acknowledgments
Release notes for significant contributions
Annual contributor highlights

Licensing

By contributing to Pingplop, you agree that your contributions will be licensed under the same license as the project. When contributing to a Pingplop feature, you can find the relevant license in the comments at the top of each file.

For more information about Pingplop licensing, see the Licensing Agreement page.

Questions?

Don't hesitate to ask questions! We're here to help and want to make contributing as smooth as possible. Whether you're fixing a typo or adding a major feature, all contributions are valuable and appreciated.

Thank you for contributing to Pingplop! 🚀