Contributing Guidelines - Wal33D/manic-miners-launcher GitHub Wiki

Contributing Guidelines

Thank you for your interest in contributing to the Manic Miners Launcher! This guide will help you get started with contributing to the project.

Getting Started

Prerequisites

Before contributing, make sure you have:

  1. Development Environment - Follow our Development Setup guide
  2. Understanding of the Project - Read the Project Architecture overview
  3. GitHub Account - For submitting pull requests and issues

Code of Conduct

By participating in this project, you agree to:

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help maintain a positive community environment
  • Follow the project's coding standards and practices

How to Contribute

🐛 Reporting Bugs

Before creating a bug report:

  1. Check existing GitHub Issues
  2. Make sure you're using the latest version
  3. Try to reproduce the issue consistently

When creating a bug report, include:

  • Clear title describing the issue
  • Environment details: OS, launcher version, Node.js version
  • Steps to reproduce the bug
  • Expected behavior vs actual behavior
  • Screenshots or videos if applicable
  • Log files from the launcher logs directory
  • Error messages (copy the exact text)

Bug Report Template:

## Bug Description
A clear description of what the bug is.

## Environment
- OS: [e.g., Windows 11, macOS 13.1, Ubuntu 22.04]
- Launcher Version: [e.g., 1.2.3]
- Node.js Version: [e.g., 20.11.0]

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Additional Context
Any other context, screenshots, or log files.

💡 Suggesting Features

Before suggesting a feature:

  1. Check if it's already been suggested in Issues
  2. Consider if it fits the project's scope and goals
  3. Think about how it would benefit other users

When suggesting a feature, include:

  • Clear title and description
  • Use case - why is this feature needed?
  • Proposed solution - how should it work?
  • Alternatives considered - other ways to solve the problem
  • Additional context - mockups, examples, references

🔧 Contributing Code

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/manic-miners-launcher.git
cd manic-miners-launcher

# Add the original repository as upstream
git remote add upstream https://github.com/Wal33D/manic-miners-launcher.git

2. Create a Branch

# Create a new branch for your feature/fix
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Branch naming conventions:

  • feature/feature-name - For new features
  • fix/issue-description - For bug fixes
  • docs/update-description - For documentation updates
  • refactor/component-name - For code refactoring
  • test/test-description - For adding or updating tests

3. Make Your Changes

Follow these guidelines:

Code Style:

  • Use TypeScript for all new code
  • Follow existing code formatting (Prettier configuration)
  • Use meaningful variable and function names
  • Add JSDoc comments for public functions
  • Follow React best practices for frontend components

File Organization:

  • Place backend code in src/
  • Place frontend code in launcher-gui/src/
  • Add tests alongside the code they test
  • Update documentation as needed

Commit Messages: Use conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat - New features
  • fix - Bug fixes
  • docs - Documentation updates
  • style - Code style changes (formatting, etc.)
  • refactor - Code changes that neither fix bugs nor add features
  • test - Adding or updating tests
  • chore - Maintenance tasks

Examples:

git commit -m "feat(download): add progress tracking for itch.io downloads"
git commit -m "fix(ui): resolve notification overlay z-index issue"
git commit -m "docs(api): update IPC channel documentation"

4. Test Your Changes

Before submitting:

# Install dependencies
pnpm install

# Run linting
pnpm run lint

# Run tests
pnpm test

# Test the build
pnpm run build

# Test packaging (if relevant)
pnpm run package

Testing checklist:

  • All existing tests pass
  • New features have appropriate tests
  • Code follows the project's style guidelines
  • No console errors in development mode
  • Application builds successfully
  • Manual testing completed for changes

5. Submit a Pull Request

# Push your branch to your fork
git push origin feature/your-feature-name

Create a pull request with:

  • Clear title describing what the PR does
  • Description explaining the changes and why they're needed
  • Link to related issues (if applicable)
  • Screenshots/videos for UI changes
  • Testing instructions for reviewers

Pull Request Template:

## Description
Brief description of changes made.

## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Related Issues
Fixes #(issue number)

## Testing
- [ ] I have tested these changes locally
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] All tests pass locally

## Screenshots (if applicable)
Add screenshots or videos demonstrating the changes.

## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] Any dependent changes have been merged and published

Development Workflow

Setting Up Your Environment

  1. Install Prerequisites

    # Node.js 20.19.2+
node --version

# pnpm 10.12.4
pnpm --version

  2. Clone and Setup

    git clone https://github.com/YOUR-USERNAME/manic-miners-launcher.git
cd manic-miners-launcher
pnpm install
pnpm run generate:assets

  3. Start Development

    pnpm start

Working with the Codebase

Backend Development (Electron Main Process):

  • Files in src/
  • Handle system operations, file management, IPC
  • Restart required for changes
  • Use Node.js APIs and Electron APIs

Frontend Development (React Renderer):

  • Files in launcher-gui/src/
  • Handle user interface and user experience
  • Hot reload enabled
  • Use React, TypeScript, Tailwind CSS

IPC Communication:

  • Define channels in src/main/ipcHandlers/ipcChannels.ts
  • Add handlers in appropriate handler files
  • Update preload script to whitelist new channels
  • Document in the API Reference

Code Review Process

What reviewers look for:

  1. Functionality - Does the code work as intended?
  2. Code Quality - Is it readable, maintainable, and well-structured?
  3. Testing - Are there appropriate tests?
  4. Documentation - Is it properly documented?
  5. Performance - Are there any performance implications?
  6. Security - Are there any security concerns?
  7. Breaking Changes - Will this break existing functionality?

Response to Reviews:

  • Be open to feedback and suggestions
  • Ask questions if something isn't clear
  • Make requested changes promptly
  • Thank reviewers for their time and effort

Areas for Contribution

🚀 High Priority

  1. Cross-Platform Support

    • Improve macOS and Linux compatibility
    • Test game launching on different platforms
    • Handle platform-specific file paths and permissions

  2. Performance Optimization

    • Optimize download and extraction performance
    • Improve UI responsiveness during operations
    • Reduce memory usage and startup time

  3. User Experience

    • Improve error messages and user feedback
    • Add more intuitive UI elements
    • Enhance accessibility features

🛠️ Medium Priority

  1. Testing

    • Add more comprehensive unit tests
    • Create integration tests for IPC communication
    • Add end-to-end testing for user workflows

  2. Documentation

    • Improve inline code documentation
    • Create video tutorials or guides
    • Translate documentation to other languages

  3. Features

    • Game mod support and management
    • Backup and restore functionality
    • Theme customization options

📚 Good First Issues

Perfect for newcomers to the project:

  1. Documentation improvements

    • Fix typos or unclear explanations
    • Add missing JSDoc comments
    • Update outdated screenshots

  2. UI/UX enhancements

    • Improve button styles or layouts
    • Add loading states to components
    • Fix minor visual inconsistencies

  3. Code cleanup

    • Remove unused imports or variables
    • Add TypeScript types to untyped code
    • Refactor repetitive code into reusable functions

  4. Testing

    • Add unit tests for utility functions
    • Create test cases for edge conditions
    • Improve test coverage for existing code

Recognition

Contributors will be:

  • Listed in the project README (for significant contributions)
  • Mentioned in release notes when their features are released
  • Added to the contributors page on the wiki
  • Given commit access after consistent, quality contributions

Questions and Support

Need help?

  • 💬 Discussions - Use GitHub Discussions for questions
  • 📧 Issues - Create an issue for bugs or feature requests
  • 📖 Documentation - Check our wiki
  • 🔍 Code - Look at existing code for examples

Stuck on something? Don't hesitate to ask! We're here to help newcomers learn and contribute effectively.

Ready to contribute? Check out the good first issues or start with our Development Setup guide!