Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
306 lines (216 loc) · 9.16 KB

CONTRIBUTING.md

File metadata and controls

306 lines (216 loc) · 9.16 KB

Contributing to MakeMKV Auto Rip

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

🤝 Welcome Contributors

We welcome contributions of all kinds:

  • 🐛 Bug reports and fixes
  • ✨ New features and enhancements
  • 📚 Documentation improvements
  • 🧪 Tests and quality improvements
  • 🌍 Platform compatibility (Linux, macOS)
  • 🎨 User interface improvements

🚀 Getting Started

Prerequisites

General Development

  • Node.js >= 20.0.0
  • Git for version control
  • MakeMKV installed for testing

Platform-Specific Requirements

For Windows Optical Drive Development:

  • Visual Studio 2022+ with "Desktop development with C++" workload (VS 2022 build tools with that workload will work as well)
  • Python 3.12+ (for node-gyp compilation)
  • Windows 10+ (for testing drive operations)
  • Administrator privileges (for testing drive control)

For Web UI Development:

  • Any Platform - Windows, macOS, or Linux
  • Modern Browser - For testing web interface
  • No build tools required - Uses pre-built native components

For Other Features:

  • Any Platform - Windows, macOS, or Linux
  • No build tools required - Uses pre-built native components (only used for Windows anyways)

Development Setup

  1. Fork the repository on GitHub
  2. Clone your fork: 
    git clone https://github.com/YOUR-USERNAME/MakeMKV-Auto-Rip.git
cd MakeMKV-Auto-Rip
  3. Install dependencies: 
    npm install
  4. Create a feature branch: 
    git checkout -b feature/your-feature-name
  5. Test both interfaces: 
    npm start          # Test CLI interface
npm run web        # Test web interface at http://localhost:3000

Building Native Components (Windows Development Only)

If you're developing Windows optical drive interaction functionality, you may need to rebuild the native addon:

# Build the native addon (requires Visual Studio + Python)
npm run windows-addons:build

# Build debug version for development
npm run windows-addons:build:debug

# Clean build artifacts
npm run windows-addons:clean

Note: Most contributors won't need to build native components since:

  • Pre-built binaries are included in the repository
  • Only Windows optical drive changes require rebuilding
  • Other features work on all platforms without compilation

📋 Development Guidelines

Code Style

We follow these conventions:

  • ES6+ JavaScript with modules (import/export)
  • Async/await for asynchronous operations
  • PascalCase for classes (DiscService)
  • camelCase for functions and variables (getAvailableDiscs)
  • kebab-case for file names (disc.service.js)
  • UPPER_SNAKE_CASE for constants (MEDIA_TYPES)

Project Structure

src/
├── cli/          # Command-line interface and command handling
├── web/          # Web interface components
│   ├── routes/   # API endpoints
│   ├── middleware/ # WebSocket handling
│   └── static/   # Frontend assets (CSS, JS)
├── services/     # Business logic and external integrations
├── utils/        # Reusable utility functions
├── config/       # Configuration management
└── constants/    # Application constants

Adding New Features

  1. Services - Add business logic to appropriate service modules
  2. Utilities - Create reusable functions in utils/
  3. CLI - Update interface for user-facing changes
  4. Web UI - Update API routes and frontend for web interface changes
  5. Config - Add new configuration options if needed
  6. Documentation - Update README and relevant docs

🐛 Bug Reports

Before Submitting

  • Check existing issues to avoid duplicates
  • Test with the latest version
  • Verify the issue isn't configuration-related (check config.yaml format and values)

When you create a bug report, GitHub will guide you through our bug report template to ensure we get all the information needed to help you. P.S. Thank you so much for helping to improve MakeMKV Auto Rip in any capacity! Your feedback is truly appreciated!

💡 Feature Requests

We welcome feature requests! When you create a feature request issue, GitHub will guide you through our template to help us understand your needs and use case. P.S. Thank you so much for contributing to MakeMKV Auto Rip! Your assistance benefits everyone!

🔧 Development Workflow

Making Changes

  1. Write clean, documented code
  2. Follow existing patterns in the codebase
  3. Add JSDoc comments for public methods
  4. Test your changes thoroughly
  5. Update documentation as needed

Commit Guidelines

Use clear, descriptive commit messages:

# Good
git commit -m "Add parallel processing for multiple disc ripping"
git commit -m "Fix drive ejection issue on USB drives"
git commit -m "Update README with new YAML configuration options"

# Less good
git commit -m "Fix bug"
git commit -m "Update stuff"

Pull Request Process

  1. Ensure your branch is up to date:

    git fetch upstream
git rebase upstream/master

  2. Test your changes: (Pick those which apply)

    npm start  # Test CLI functionality
npm run web  # Test web interface
npm run load  # Test drive loading
npm run eject  # Test drive ejection
npm run windows-addons:build # Test Windows drive load/eject addon
npm run docker:build  # Test Docker build
npm run docker:run  # Test Docker deployment

  3. Create a pull request with:

    • Clear title and description
    • Reference to related issues
    • Description of changes made
    • Testing performed

When you create a pull request, GitHub will automatically populate it with our pull request template to ensure all necessary information is included.

🧪 Testing

Manual Testing

  • Test with different disc types (if possible) (DVD, Blu-ray)
  • Test with multiple drives when possible
  • Test error scenarios (missing discs, invalid YAML config)
  • Test all npm (usage) commands (start, load, eject)
  • Test web interface - Verify all operations work through web UI
  • Test responsive design - Check web UI on different screen sizes
  • Test real-time features - Verify WebSocket connections and live updates

Future: Automated Testing

We're planning to add:

  • Unit tests for utility functions
  • Integration tests for services
  • End-to-end testing workflows

🌍 Cross-Platform Support

Cross-platform support now available!

  • Windows - Full native support with drive loading/ejecting
  • Linux - Full functionality tested on Ubuntu based Linux
  • macOS - Theoretical support (testing & platform fix contributions welcome!)
  • Docker containers - Complete containerization with volume management

Docker Development

Test your changes with Docker:

npm run docker:build    # Build the Docker image
npm run docker:run      # Start container with docker-compose
npm run docker:logs     # View container logs
npm run docker:stop     # Stop the container

Platform-Specific Features

  • Drive operations are automatically disabled in Docker/Linux environments
  • MakeMKV paths adapt automatically to the target platform
  • Dependencies are conditionally loaded based on the environment

📚 Documentation

Documentation Standards

  • Clear examples - Include working code examples
  • Up-to-date - Keep in sync with code changes
  • Accessible - Use clear language and formatting

Types of Documentation

  • README.md - Main user documentation
  • PROJECT-INFO.md - Technical architecture details
  • CONTRIBUTING.md - This file
  • CHANGELOG.md - Version history
  • JSDoc - Inline code documentation

🏷️ Release Process

Version Numbers

We follow Semantic Versioning:

  • MAJOR - Breaking changes
  • MINOR - New features (backward compatible)
  • PATCH - Bug fixes (backward compatible)

Release Checklist

  1. Update version in package.json
  2. Update CHANGELOG.md
  3. Test thoroughly
  4. Create release tag
  5. Update documentation

📞 Getting Help

Questions and Support

  • GitHub Issues - For bugs and feature requests
  • GitHub Discussions - For questions and general discussion
  • Email - For private/security concerns

Response Times

  • We aim to respond to issues within 24-72 hours (this is a side-project and not part of my day-job, but I'll fit in time as much as I'm able to!)
  • Pull requests reviewed within one week
  • We're a small project, so patience is appreciated!

🙏 Recognition

Contributors will be:

  • Listed in the project contributors
  • Credited in release notes for significant contributions
  • Welcomed as maintainers for sustained contributions

📄 License

By contributing, you agree that your contributions will be licensed under the same GPL-3.0-or-later license that covers the project.

Thank you for contributing to MakeMKV Auto Rip! 🎉

Your contributions help make disc ripping easier for everyone. Whether it's fixing a small bug or adding a major feature, every contribution is valuable and appreciated.