diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..c22a31c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: Report a problem with macapptree +labels: bug +--- + +## Description + +A clear description of the bug. + +## Environment + +- macOS version: +- Python version: +- macapptree version: +- Installation method (pip / source): + +## Accessibility permission granted? + +- [ ] Yes — terminal / Python has Accessibility access in System Settings + +## Steps to reproduce + +```python +# Minimal example that triggers the bug +``` + +## Expected behavior + +What you expected to happen. + +## Actual behavior + +What actually happened. Include any error messages or stack traces. + +## Additional context + +Any other relevant information (app being captured, window state, etc.). diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..b8ae2b8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,29 @@ +--- +name: Feature request +about: Suggest an improvement or new capability +labels: enhancement +--- + +## Summary + +A one-line description of the feature. + +## Motivation + +Why is this useful? What problem does it solve? + +## Proposed API / behavior + +If applicable, show what the interface would look like: + +```python +# Example usage +``` + +## Alternatives considered + +Other approaches you thought about and why you prefer this one. + +## Additional context + +Links, screenshots, related issues, or anything else relevant. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..0f22ffa --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +## Summary + +Describe what this PR does and why. + +## Changes + +- +- + +## Type of change + +- [ ] Bug fix +- [ ] New feature +- [ ] Refactor / cleanup +- [ ] Documentation +- [ ] Other: + +## Testing + +Describe how you tested the change. Include the app bundle IDs you used, macOS version, and any edge cases exercised. + +## Checklist + +- [ ] Tested on macOS with Accessibility permission granted +- [ ] No hardcoded paths or bundle IDs left in the code +- [ ] Follows existing code conventions (see [CONTRIBUTING.md](../CONTRIBUTING.md)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..96450c8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# Contributing to macapptree + +Thank you for your interest in contributing! This document covers how to set up the project locally, the workflow for submitting changes, and our conventions. + +--- + +## Prerequisites + +- macOS (the package uses macOS-only APIs) +- Python 3.8 or later +- Your terminal must have **Accessibility** permission granted in System Settings → Privacy & Security → Accessibility + +--- + +## Development setup + +```bash +# 1. Clone the repo +git clone https://github.com/MacPaw/macapptree.git +cd macapptree + +# 2. Create and activate a virtual environment +python -m venv .venv +source .venv/bin/activate + +# 3. Install with dev dependencies +pip install -e ".[dev]" +``` + +--- + +## Running tests + +```bash +pytest +``` + +Since the library relies on live macOS Accessibility APIs, most tests require a running macOS session with the appropriate permissions. Tests that depend on a specific application being open are skipped automatically when that app is not available. + +--- + +## Submitting changes + +1. Fork the repository and create a feature branch from `main`: + ```bash + git checkout -b feat/my-feature + ``` +2. Make your changes and commit with a clear message: + ``` + feat: add support for AXSheet elements + fix: handle missing kCGWindowBounds gracefully + ``` +3. Open a pull request against `main` and fill in the PR template. + +--- + +## Code conventions + +- Follow [PEP 8](https://peps.python.org/pep-0008/) style. +- Keep public functions typed where practical. +- No comments explaining *what* the code does — names should do that. Comments should only explain *why* (hidden constraints, workarounds, non-obvious invariants). +- Keep pull requests focused: one logical change per PR. + +--- + +## Reporting bugs + +Use [GitHub Issues](https://github.com/MacPaw/macapptree/issues). Include: + +- macOS version and Python version +- Minimal reproducible example +- Expected vs. actual behavior + +For security vulnerabilities, follow the process described in [SECURITY.md](SECURITY.md) instead. + +--- + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).