Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (141 loc) · 4.75 KB

CONTRIBUTING.md

File metadata and controls

197 lines (141 loc) · 4.75 KB
Raw

Contributing to PulseCheck

Thank you for your interest in contributing to PulseCheck! This guide will help you understand the project structure and development workflow.

Project Overview

PulseCheck is a distributed service health monitoring system built in Go. It uses a worker-pool architecture to monitor multiple HTTP services concurrently, demonstrating Go's concurrency model with goroutines and channels.

Architecture

Core Components

  1. Worker Pool Pattern: Producer-consumer pattern with buffered channels for URLs and a fixed number of workers
  2. Concurrent URL Checking: Goroutines to visit multiple URLs simultaneously
  3. Channel Communication: Channels distribute work to workers and collect results
  4. Database Integration: SQLite for persistent storage of URLs and check results
  5. Notification System: Interface-based system supporting Slack, Discord, and Email
  6. REST API: HTTP API for programmatic access
  7. Scheduler: Time-based scheduling for periodic URL checks

Codebase Structure

cmd/
├── pulsecheck/              # CLI application
│   ├── main.go
│   └── cli/                 # CLI commands
└── pulsecheck-server/       # REST API server
    └── main.go

internal/
├── api/                     # REST API endpoints
├── checker/                 # Worker pool & URL checking
├── config/                  # Configuration management
├── database/                # SQLite operations
├── notifier/                # Notification system
├── scheduler/               # Check scheduling
└── urlmanager/              # Data structures

Development Setup

Prerequisites

  • Go 1.25 or higher
  • Git

Getting Started

# Clone the repository
git clone https://github.com/gyaan/pulse-check.git
cd pulse-check

# Install dependencies
go mod download

# Build the project
make build

# Run tests
make test

Development Commands

# Build both binaries
make build

# Run tests
make test

# Clean build artifacts
make clean

# Run the CLI
./pulsecheck-cli --help

# Run the server
./pulsecheck-server-api

Making Changes

Code Style

  • Follow standard Go conventions (use gofmt and go vet)
  • Write clear, descriptive commit messages
  • Add tests for new functionality
  • Update documentation as needed

Testing

All new features should include tests:

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for specific package
go test ./internal/checker -v

Submitting Changes

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature
  3. Make your changes
  4. Run tests: make test
  5. Commit your changes: git commit -m "Add: description of changes"
  6. Push to your fork: git push origin feature/your-feature
  7. Submit a Pull Request

Architecture Notes

Concurrency Model

The system uses:

  • Buffered channels for work distribution
  • WaitGroups for synchronization
  • Goroutines for concurrent execution
  • Context for cancellation

Database

SQLite integration:

  • Pure Go driver (no CGO required)
  • WAL mode for better concurrency
  • Transaction support for atomic operations
  • Prepared queries for security

Configuration

The configuration system supports:

  • YAML files
  • Environment variables
  • Command-line flags
  • Sensible defaults

Priority: Flags > Environment > Config File > Defaults

Best Practices

SQLite

  • Use a single database connection with proper locking
  • Wrap related operations in transactions
  • Enable WAL mode for concurrent reads/writes
  • Plan for backward-compatible schema changes

Goroutines

  • Always ensure proper cleanup of goroutines
  • Use defer for resource cleanup
  • Implement graceful shutdown handling
  • Track goroutines with WaitGroups

Performance

  • Reuse buffers and limit channel sizes appropriately
  • Monitor resource usage
  • Use connection pooling where appropriate
  • Profile before optimizing

Security

  • Validate all user input
  • Use parameterized queries
  • Implement SSRF protection for URL checking
  • Handle secrets via environment variables

Project Goals

  1. Educational: Demonstrate Go concurrency patterns
  2. Practical: Provide useful service monitoring
  3. Production-Ready: Include enterprise features
  4. Well-Documented: Clear code and documentation
  5. Tested: Comprehensive test coverage

Getting Help

  • Open an issue for bugs or feature requests
  • Check existing issues before creating new ones
  • Provide clear reproduction steps for bugs
  • Include relevant logs and configuration

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • Collaborate openly

Thank you for contributing to PulseCheck!