easystream-main/docs/CONTRIBUTING.md

Contributing to EasyStream

Thank you for your interest in contributing to EasyStream! This document provides guidelines and information for contributors.

Development Setup

Prerequisites

• Docker and Docker Compose
• PHP 8.2+ (for local development)
• Node.js (for frontend assets)
• Git

Quick Start

1. Clone the repository
2. Copy .env.example to .env and configure
3. Run docker-compose up -d --build
4. Access the application at http://localhost:8083

Project Structure

Core Directories

• f_core/ - Framework core (classes, functions, configs)
• f_modules/ - Feature modules (frontend/backend)
• f_templates/ - Smarty templates
• f_data/ - Runtime data (logs, cache, uploads)
• f_jobs/ - Background job classes
• api/ - API endpoints
• tests/ - Test suites

Key Files

• index.php - Main application entry point
• docker-compose.yml - Container orchestration
• Caddyfile - Web server configuration
• deploy/srs.conf - Live streaming server config

Development Guidelines

Code Standards

• Follow PSR-12 coding standards for PHP
• Use meaningful variable and function names
• Add PHPDoc comments for all classes and methods
• Validate all user inputs using VSecurity class
• Use prepared statements for database queries

Security Best Practices

• Always use VSecurity::getParam() and VSecurity::postParam() for input
• Implement CSRF protection with csrf_field() and validate_csrf()
• Escape output with secure_output() and secure_js()
• Use rate limiting for sensitive operations
• Log security events with VLogger

Database Guidelines

• Use VDatabase class for all database operations
• Validate table and field names
• Use parameter binding for queries
• Follow the existing schema patterns

Testing

• Write unit tests for new functionality
• Use PHPUnit for testing
• Run tests with ./run-tests.sh
• Ensure all tests pass before submitting PRs

Feature Development

Adding New Features

1. Create a spec in .kiro/specs/feature-name/
2. Write requirements, design, and tasks
3. Implement following the task list
4. Add appropriate tests
5. Update documentation

Live Streaming Features

• Use SRS for RTMP/HLS streaming
• HLS files are served from /hls/ endpoint
• DVR recordings stored in /srs/rec/
• Test streaming with OBS or similar tools

API Development

• Follow RESTful principles
• Use proper HTTP status codes
• Implement rate limiting
• Add comprehensive error handling
• Document all endpoints

Deployment

Production Checklist

• Review DEPLOYMENT-CHECKLIST.md
• Configure environment variables
• Set up SSL certificates
• Configure backup procedures
• Monitor logs and performance

Docker Deployment

• Use provided docker-compose.yml
• Configure volumes for persistent data
• Set up reverse proxy (Caddy included)
• Configure SRS for live streaming

Troubleshooting

Common Issues

• Check f_data/logs/ for error logs
• Verify database connectivity
• Ensure proper file permissions
• Check Docker container logs

Debug Mode

• Enable debug mode in configuration
• Use VLogger for detailed logging
• Check admin log viewer for issues

Getting Help

Documentation

• Read the main README.md
• Check docs/API.md for API details
• Review deployment guides in docs/

Support

• Create GitHub issues for bugs
• Use discussions for questions
• Follow the issue templates

Code Review Process

Pull Request Guidelines

1. Create feature branch from main
2. Make focused, atomic commits
3. Write clear commit messages
4. Add tests for new functionality
5. Update documentation as needed
6. Ensure CI passes

Review Criteria

• Code follows project standards
• Security best practices implemented
• Tests cover new functionality
• Documentation is updated
• No breaking changes without discussion

License

By contributing to EasyStream, you agree that your contributions will be licensed under the same license as the project.