0b7e2d0a5b
- Created complete documentation in docs/ directory - Added PROJECT_OVERVIEW.md with feature highlights and getting started guide - Added ARCHITECTURE.md with system design and technical details - Added SECURITY.md with comprehensive security implementation guide - Added DEVELOPMENT.md with development workflows and best practices - Added DEPLOYMENT.md with production deployment instructions - Added API.md with complete REST API documentation - Added CONTRIBUTING.md with contribution guidelines - Added CHANGELOG.md with version history and migration notes - Reorganized all documentation files into docs/ directory for better organization - Updated README.md with proper documentation links and quick navigation - Enhanced project structure with professional documentation standards
145 lines
3.9 KiB
Markdown
145 lines
3.9 KiB
Markdown
# 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. |