Contributing to MenuCLI 🤝

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

📋 Table of Contents

Code of Conduct
Getting Started
Development Setup
Contributing Guidelines
Submitting Changes
Bug Reports
Feature Requests
Code Style
Testing
Documentation

📜 Code of Conduct

This project and everyone participating in it is governed by our commitment to creating a welcoming and inclusive environment. By participating, you are expected to uphold high standards of respect and professionalism.

Our Standards

Be respectful - Treat all contributors with dignity and respect
Be inclusive - Welcome newcomers and different perspectives
Be collaborative - Work together constructively
Be helpful - Share knowledge and assist others
Be patient - Remember that everyone has different experience levels

🚀 Getting Started

Prerequisites

macOS 10.15 (Catalina) or later
Xcode 12.0+ or Swift 5.9+ toolchain
Git
Basic familiarity with Swift and command-line tools

Development Setup

Fork the repository

# Click "Fork" on GitHub, then clone your fork
git clone https://github.com/yourusername/menucli.git
cd menucli

Set up upstream remote

git remote add upstream https://github.com/originalowner/menucli.git

Build the project
```
swift build
./build.sh
```

Run tests

./test.sh
swift test  # When unit tests are available

Grant accessibility permissions
- Add Terminal to Accessibility permissions in System Preferences
- This is required for development and testing

🛠️ Contributing Guidelines

Types of Contributions

We welcome several types of contributions:

🐛 Bug fixes - Fix issues in existing functionality
✨ New features - Add new capabilities to MenuCLI
📚 Documentation - Improve README, code comments, or guides
🧪 Tests - Add or improve test coverage
🎨 Code quality - Refactoring, performance improvements
🔧 Build system - Improve build scripts, CI/CD, packaging

Before You Start

Check existing issues - Search for existing issues or discussions
Open an issue first - For major changes, discuss your approach
Start small - Consider starting with small bug fixes or documentation
Ask questions - Don't hesitate to ask for help or clarification

📝 Submitting Changes

Branch Naming

Use descriptive branch names with prefixes:

feature/add-fuzzy-matching - New features
fix/ellipsis-handling-bug - Bug fixes
docs/improve-readme - Documentation updates
refactor/menu-helper-cleanup - Code refactoring
test/add-unit-tests - Testing improvements

Commit Messages

Write clear, descriptive commit messages:

<type>: <description>

<optional body>

<optional footer>

Types:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
style: - Code style changes (formatting, etc.)
refactor: - Code refactoring
test: - Adding or updating tests
chore: - Build system, dependencies, etc.

Examples:

feat: add fuzzy matching for menu items

Implements approximate string matching to handle typos and variations
in menu item names. Uses Levenshtein distance with configurable threshold.

Closes #42

fix: handle ellipsis character conversion properly

- Convert ... to … in AppleScript bridge
- Add normalization for menu discovery
- Update tests for typography handling

Fixes #38

Pull Request Process

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Write clean, well-commented code
- Follow existing code style
- Add tests if applicable
- Update documentation as needed

Test your changes

swift build
./test.sh
# Test with various applications manually

Commit your changes

git add .
git commit -m "feat: add your feature description"

Update your branch

git fetch upstream
git rebase upstream/main

Push to your fork

git push origin feature/your-feature-name

Create Pull Request
- Use the GitHub interface to create a PR
- Fill out the PR template completely
- Link related issues
- Request review from maintainers

Pull Request Template

When creating a PR, include:

## Description
Brief description of changes and motivation.

## Type of Change
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to change)
- [ ] Documentation update

## Testing
- [ ] Tested with multiple applications
- [ ] Added/updated unit tests
- [ ] Manual testing completed
- [ ] Accessibility permissions working

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Changes tested on macOS versions: ___

🐛 Bug Reports

Before Reporting

Search existing issues - Check if already reported
Test latest version - Ensure bug exists in current release
Minimal reproduction - Create smallest possible example

Bug Report Template

**Bug Description**
Clear description of the bug.

**To Reproduce**
Steps to reproduce:
1. Run command: `menu click Safari "File > New Window"`
2. Observe error: ...

**Expected Behavior**
What should happen.

**Actual Behavior**
What actually happens.

**Environment**
- macOS version: 
- MenuCLI version:
- Application tested:
- Terminal app:

**Additional Context**
- Verbose output: `menu click ... --verbose`
- Screenshots if helpful
- Relevant error messages

✨ Feature Requests

Before Requesting

Check existing requests - Search issues and discussions
Consider scope - Ensure it fits MenuCLI's purpose
Think about implementation - Consider technical feasibility

Feature Request Template

**Feature Description**
Clear description of the proposed feature.

**Use Case**
Why is this feature needed? What problem does it solve?

**Proposed Solution**
How do you envision this working?

**Alternatives Considered**
Other approaches you've considered.

**Additional Context**
Examples, mockups, related tools, etc.

🎨 Code Style

Swift Style Guidelines

Follow Swift best practices:

Use meaningful variable and function names
Keep functions focused and small
Add comprehensive comments for complex logic
Use Swift's type system effectively
Follow Apple's Swift API Design Guidelines

Code Organization

// File header with brief description
import Foundation
import ApplicationServices

// MARK: - Main Class/Struct
class MenuHelper {
    // MARK: - Properties
    var verbose: Bool = false
    
    // MARK: - Public Methods
    func publicMethod() {
        // Implementation
    }
    
    // MARK: - Private Methods
    private func privateMethod() {
        // Implementation
    }
}

// MARK: - Extensions
extension MenuHelper {
    // Extension methods
}

Documentation

Use Swift documentation comments (///)
Document public APIs thoroughly
Include parameter and return value descriptions
Add usage examples for complex functions

/// Clicks a menu item following a specified path
/// 
/// - Parameters:
///   - app: The target application's AXUIElement
///   - menuPath: Array of menu names forming the path (e.g., ["File", "New Window"])
///   - methods: Optional execution methods to try
/// - Returns: True if the menu item was successfully clicked
/// 
/// Example:
/// ```swift
/// let success = clickMenuItem(app: safariApp, menuPath: ["File", "New Window"])
/// ```
func clickMenuItem(app: AXUIElement, menuPath: [String], methods: [ExecutionMethod]? = nil) -> Bool {
    // Implementation
}

🧪 Testing

Manual Testing

Always test changes with:

Multiple applications (Safari, Finder, VS Code, etc.)
Different menu structures (simple, nested, with ellipsis)
Various execution methods
Both visual and non-visual modes
Error conditions (app not running, menu not found)

Test Checklist

Before submitting:

Adding Unit Tests

When unit tests are added to the project:

import XCTest
@testable import MenuCLI

class MenuHelperTests: XCTestCase {
    func testMenuTitleNormalization() {
        let helper = MenuHelper()
        let variations = helper.normalizeMenuTitle("Save...")
        XCTAssertTrue(variations.contains("Save…"))
    }
}

📚 Documentation

Types of Documentation

Code comments - Explain complex logic
API documentation - Swift documentation comments
README updates - Keep examples current
CHANGELOG - Document all changes
Guides - How-to documentation for users

Documentation Standards

Use clear, concise language
Include practical examples
Keep documentation up-to-date with code changes
Test all code examples
Use proper Markdown formatting

🏷️ Labels and Issues

Issue Labels

bug - Something isn't working
enhancement - New feature or improvement
documentation - Documentation needs
good first issue - Good for newcomers
help wanted - Extra attention needed
question - Further information requested
wontfix - Valid issue that won't be fixed

Priority Labels

priority: high - Critical issues
priority: medium - Important improvements
priority: low - Nice to have

💡 Tips for Contributors

Getting Familiar

Read the code - Start by exploring the codebase
Use the tool - Become familiar with all features
Check issues - Look for good first issue labels
Ask questions - Join discussions, ask for help

Best Practices

Start small - Begin with documentation or small fixes
Be patient - Code review takes time
Learn from feedback - Use reviews to improve
Stay updated - Follow project changes
Have fun - Enjoy the process!

Communication

Be respectful - Professional communication always
Be clear - Explain your thinking and approach
Be responsive - Respond to feedback promptly
Be collaborative - Work together toward solutions

🎯 Development Roadmap

Current Priorities

Stability - Bug fixes and reliability improvements
Performance - Optimization and caching
Testing - Comprehensive test suite
Documentation - Examples and guides

Future Directions

Homebrew formula
Menu structure caching
Plugin architecture
Performance monitoring
Enhanced error messages

📞 Getting Help

Resources

GitHub Issues - For bugs and feature requests
GitHub Discussions - For questions and ideas
Code Review - Learn from maintainer feedback
Documentation - README and inline comments

Contact

Create an issue for specific problems
Use discussions for general questions
Tag maintainers for urgent issues
Be patient - maintainers are volunteers

🙏 Thank You

Your contributions make MenuCLI better for everyone. Whether you're fixing typos, adding features, or helping other users, every contribution is valued and appreciated.

Welcome to the MenuCLI community! 🎉

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History