Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
205 lines (156 loc) · 5.39 KB

CONTRIBUTING.md

File metadata and controls

205 lines (156 loc) · 5.39 KB

Contributing to GitHub Runner Mobile

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.

Code of Conduct

Be respectful, inclusive, and professional. We're all here to build better tools together.

How to Contribute

Reporting Bugs

Found a bug? Please open a GitHub Issue with:

  • Clear title describing the problem
  • macOS version (e.g., macOS 14.2)
  • Ansible version (ansible --version)
  • Steps to reproduce the issue
  • Expected behavior vs actual behavior
  • Error messages and relevant logs
  • Screenshots if applicable

Suggesting Features

Have an idea? Open a GitHub Issue with:

  • Clear description of the feature
  • Use case: Why is this useful?
  • Proposed implementation (if you have ideas)
  • Alternatives considered

Submitting Changes

  1. Fork the repository
  2. Create a feature branch 
    git checkout -b feature/your-feature-name
  3. Make your changes
  4. Test thoroughly
    • Run playbooks on clean macOS machine
    • Verify idempotency (run twice, same result)
    • Check for syntax errors
  5. Commit with clear messages 
    git commit -m "Add feature: description of what you did"
  6. Push to your fork 
    git push origin feature/your-feature-name
  7. Open a Pull Request

Development Guidelines

Code Style

Ansible/YAML:

  • Use 2 spaces for indentation (not tabs)
  • Use descriptive task names
  • Add comments for complex logic
  • Follow Ansible best practices
  • Use when conditions over failed_when: false
  • Make tasks idempotent

Shell Scripts:

  • Use #!/bin/bash shebang
  • Set error handling: set -euo pipefail
  • Add comments for non-obvious code
  • Use meaningful variable names
  • Quote variables: "$VAR" not $VAR

Python:

  • Follow PEP 8 style guide
  • Use meaningful variable names
  • Add docstrings to functions
  • Use type hints where appropriate

Testing

Before submitting:

  • Playbooks run successfully on Apple Silicon macOS
  • Playbooks are idempotent (can run multiple times)
  • No hardcoded values (use variables)
  • No sensitive data in code
  • YAML syntax is valid (ansible-playbook --syntax-check)
  • Updated documentation if needed
  • No breaking changes (or clearly documented)

Pull Request Process

  1. Update documentation if you're changing functionality
  2. Keep changes focused - one feature/fix per PR
  3. Describe your changes:
    • What problem does this solve?
    • How does it work?
    • Any breaking changes?
    • Testing performed?
  4. Be responsive to review feedback
  5. Squash commits if requested

Commit Message Format

Use clear, descriptive commit messages:

Add feature: support for custom runner groups

- Add runner_group variable to vars/main.yml
- Update runner.sh to use configurable group
- Add documentation for runner groups

Good commit messages:

  • ✅ Fix: Android SDK path detection on Intel Macs
  • ✅ Add: support for Xcode 15.x
  • ✅ Update: README with better Quick Start guide
  • ✅ Refactor: simplify runner creation logic

Bad commit messages:

  • ❌ fix bug
  • ❌ update
  • ❌ WIP
  • ❌ asdf

Project Structure

.
├── ansible/               # Ansible playbooks and configuration
│   ├── vars/             # Configuration variables
│   ├── *.yml             # Playbook files
│   └── inventory.ini     # Inventory template
├── runner/               # Runner management scripts
├── tools/                # Additional utilities
├── docs/                 # Documentation
└── .github/              # GitHub templates and workflows

Adding New Features

Adding a New Playbook

  1. Create playbook in ansible/
  2. Follow existing playbook structure
  3. Add to site.yml with appropriate tags
  4. Document in README.md
  5. Add configuration variables to vars/main.yml.example
  6. Test on fresh macOS installation

Adding New Configuration

  1. Add variable to ansible/vars/main.yml.example
  2. Document in docs/CONFIGURATION.md
  3. Update README if it's a major option
  4. Provide sensible defaults
  5. Add validation if required

Adding New Documentation

  1. Create markdown file in appropriate location
  2. Link from README.md
  3. Use clear headings and examples
  4. Keep it concise and actionable

Release Process

(For maintainers)

  1. Update CHANGELOG.md
  2. Bump version number (if applicable)
  3. Tag release: git tag -a v1.0.0 -m "Release 1.0.0"
  4. Push tag: git push origin v1.0.0
  5. Create GitHub Release with notes

Questions?

  • Open a GitHub Issue for questions
  • Check existing issues and documentation first
  • Be clear and provide context

Areas Needing Help

Current priorities for contributions:

  • Support for Intel Macs (testing and fixes)
  • Additional CI/CD platform integrations (GitLab, Jenkins)
  • Windows subsystem support
  • Docker-based runner option
  • Automated testing framework
  • More platform examples (Flutter, React Native)
  • Video tutorials and guides
  • Translations for documentation

Recognition

Contributors will be recognized in:

  • GitHub contributors list
  • CHANGELOG.md for significant contributions
  • README.md acknowledgments section (for major features)

Thank you for contributing to GitHub Runner Mobile! Every contribution, no matter how small, is valuable.