Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
140 lines (104 loc) · 6.99 KB

CONTRIBUTING.md

File metadata and controls

140 lines (104 loc) · 6.99 KB
Raw

Contributing to Input Source Pro

First off, thank you for considering contributing to Input Source Pro! We welcome any help, whether it's reporting a bug, proposing a feature, improving documentation, adding translations, or writing code.

This document provides guidelines to help you contribute effectively.

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to support@inputsource.pro.

How Can I Contribute?

  • Reporting Bugs: If you find a bug, please report it!
  • Suggesting Enhancements: Have an idea for a new feature or an improvement? Let us know.
  • Pull Requests: Contribute code, documentation updates, or translations.
  • Answering Questions: Help others in the GitHub Discussions section.

Reporting Bugs

Before submitting a bug report, please check the existing GitHub Issues to see if someone else has already reported it.

If not, create a new issue and provide the following information:

  1. Clear Title: Describe the issue concisely.
  2. Steps to Reproduce: Detailed steps to reliably reproduce the behavior.
  3. Expected Behavior: What you expected to happen.
  4. Actual Behavior: What actually happened. Include error messages or screenshots if applicable.
  5. Environment:
    • Input Source Pro Version (e.g., 1.2.3 Build 456 - found in left bottom corner of the app)
    • macOS Version (e.g., macOS 15.4.1 - found in "About This Mac")
    • Affected Application(s) (if applicable)
    • Relevant Input Sources used

Suggesting Enhancements

We track feature requests using GitHub Discussions. Before creating a new one, check if a similar suggestion already exists.

When submitting an enhancement suggestion, please include:

  1. Clear Title: Describe the enhancement concisely.
  2. Problem Description: What problem does this enhancement solve? Why is it needed?
  3. Proposed Solution: A clear description of the feature or improvement you envision.
  4. Alternatives Considered: (Optional) Any alternative solutions or features you've considered.
  5. Additional Context: Mockups, examples, or related information.

Your First Code Contribution / Pull Requests

Ready to contribute code? Here's how to set up and submit a pull request:

Setting Up Your Development Environment

  1. Fork the repository on GitHub.
  2. Clone your fork locally: git clone git@github.com:runjuu/InputSourcePro.git
  3. Open the project (Input Source Pro.xcodeproj) in Xcode 27 or later (Swift 6.4 or later is required by the dependencies).
  4. Dependencies are managed via Swift Package Manager (SPM) and should resolve automatically when you open the project.
  5. Build and Run the project (Cmd+R) to ensure everything is set up correctly.

Making Changes

  1. Create a new branch for your changes, based off the main branch. Use a descriptive name (e.g., feature/add-xyz-support, fix/indicator-crash). 
    git checkout main
git pull origin main
git checkout -b feature/your-descriptive-branch-name
  2. Write your code. Please try to follow the existing code style. If you add new features, consider adding tests if applicable.
  3. Ensure the project builds successfully (Cmd+B).
  4. Commit your changes with clear and concise commit messages. Reference the issue number if your PR addresses a specific issue (e.g., Fix #123: Resolve crash when switching sources rapidly). 
    git add .
git commit -m "feat: Add support for XYZ browser rule"
  5. Push your branch to your fork on GitHub: 
    git push origin feature/your-descriptive-branch-name

Submitting a Pull Request

  1. Go to the original InputSourcePro repository on GitHub.
  2. Click on "Pull Requests" and then "New pull request".
  3. Choose your fork and the branch containing your changes.
  4. Write a clear description for your Pull Request:
    • Explain the purpose of your changes.
    • Link to any relevant issues (e.g., "Closes #123").
    • Summarize the changes made.
    • Describe any testing you performed.
  5. Submit the Pull Request. A maintainer will review it as soon as possible. Be prepared to discuss your changes and make adjustments based on feedback.

Style Guides

  • Code Style: Follow the existing Swift conventions used in the project. Keep code clear and readable.
  • Git Commit Messages: Use conventional commit messages if possible (e.g., feat: ..., fix: ..., docs: ...), but clear, descriptive messages are the priority.
  • Swift Code: Follow standard Swift API Design Guidelines and try to match the style of the surrounding code.

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0 License that covers the project.

Thank you again for your interest in contributing!

Diagnosing indicator movement

Debug builds write indicator diagnostics automatically. Run the app from Xcode, reproduce the jumps, wait a second for queued writes, then quit the app normally. Collect indicator.log and indicator-previous.log (if present) from ~/Library/Logs/Input Source Pro/. Note the approximate reproduction time and which app was focused. Only run one copy of Input Source Pro while recording.

The log records input-source and Caps Lock changes, display requests and cancellations, caret-helper sample ages, Accessibility geometry and fallbacks, content sizes, and both indicator windows' visibility and frames. It excludes editor text, keystrokes, browser URLs, and window titles. Timestamps are system uptime in seconds; each session header maps uptime to a wall-clock date. Request IDs connect show, position, caret, and AX entries. An AX query may finish after cancellation; caret.delivered and show.position distinguish results that reached the UI. first() also cancels upstream after accepting a position, so a cancellation alone does not mean a result was discarded.

Writes run on a serial background queue. The current file rotates at 5 MiB and keeps one previous segment (about 10 MiB total). Copy logs soon after reproducing. Release builds leave diagnostics off unless explicitly enabled. To override either build type, set ISP_INDICATOR_DIAGNOSTICS=1 (on) or 0 (off) in the Xcode scheme's environment, or use this preference and relaunch:

defaults write com.runjuu.Input-Source-Pro IndicatorDiagnosticsEnabled -bool true

Use -bool false to disable logging, or delete the preference to restore the build default:

defaults delete com.runjuu.Input-Source-Pro IndicatorDiagnosticsEnabled

The environment setting takes precedence over the preference. Diagnostics are disabled in XCTest runs.