Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
158 lines (112 loc) · 3.93 KB

CONTRIBUTING.md

File metadata and controls

158 lines (112 loc) · 3.93 KB

Contributing to MacAutomation

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

Author

Assaf Feuerstein
DevOps Engineer | Infrastructure Automation Specialist

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

How to Contribute

Reporting Issues

  1. Check existing issues - Before creating a new issue, please check if the issue already exists.
  2. Use issue templates - When creating a new issue, provide as much detail as possible:
    • macOS version
    • Architecture (Intel or Apple Silicon)
    • Ansible version
    • Error messages and logs
    • Steps to reproduce

Submitting Changes

  1. Fork the repository and create your branch from main:

    git checkout -b feature/my-new-feature

  2. Make your changes following the coding guidelines below.

  3. Test your changes on at least one macOS version/architecture.

  4. Commit your changes with clear, descriptive commit messages:

    git commit -m "Add new role for XYZ tool installation"

  5. Push to your fork and submit a Pull Request.

Coding Guidelines

Ansible Best Practices

  • Idempotency: All tasks should be idempotent (safe to run multiple times)
  • Documentation: Include comments explaining complex logic
  • Variables: Use descriptive variable names in snake_case
  • Defaults: Always provide sensible defaults in defaults/main.yml
  • Tags: Use tags for granular playbook execution

Role Structure

Every role should follow this structure:

roles/my-role/
├── defaults/
│   └── main.yml          # Default variables
├── tasks/
│   └── main.yml          # Main tasks
├── meta/
│   └── main.yml          # Role metadata and dependencies
├── README.md             # Role documentation
├── files/                # Static files (if needed)
└── templates/            # Jinja2 templates (if needed)

Documentation

  • Every role must have a README.md with:
    • Description
    • Requirements
    • Role Variables (table format)
    • Dependencies
    • Example Playbook
    • Author attribution

Testing

  • Test roles on both Intel and Apple Silicon Macs when possible
  • Document any architecture-specific behavior
  • Use --check mode to verify idempotency

Commit Messages

Use clear, descriptive commit messages:

feat: Add new role for tool XYZ
fix: Correct path detection on Apple Silicon
docs: Update README with new examples
refactor: Simplify installation logic

Pull Request Process

  1. Update the README.md with details of changes if applicable
  2. Update role documentation if you've modified role behavior
  3. Ensure all tests pass and changes work on macOS
  4. The PR will be reviewed and merged by the maintainer

Development Setup

  1. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/MacAutomation.git
cd MacAutomation

  2. Create a virtual environment (optional but recommended):

    python3 -m venv venv
source venv/bin/activate
pip install ansible ansible-lint

  3. Install Ansible collections:

    ansible-galaxy collection install community.general

  4. Lint your playbooks:

    ansible-lint playbooks/*.yml roles/*/tasks/*.yml

Adding New Roles

When adding a new role:

  1. Create the role structure using ansible-galaxy:

    cd roles
ansible-galaxy role init my-new-role

  2. Remove unnecessary directories (keep what you need)

  3. Add author attribution to all files:

    # Author: Assaf Feuerstein

  4. Write comprehensive documentation

  5. Test on both architectures if possible

Questions?

If you have questions about contributing, feel free to open an issue with your question.

Thank you for contributing to MacAutomation!