Contribution Workflow

This guide covers the technical steps for contributing to the project.

1. Preparation

Before you start, make sure you have the repository ready:

• Contributors: Fork the repository on GitHub (pai-os) and clone your fork locally.
• Maintainers: Clone the main repository directly.

2. Create a Branch

Always create a new branch for your changes. Use a descriptive name like feature/ or bugfix/.

git checkout -b feature/your-feature-name

3. Make Your Changes

Implement your changes following our Development Standards. Make sure to:

• Test your changes locally.
• Keep your commits logical (don’t worry about perfection, as we squash anyway).

Implementation Philosophy

We follow a pathfinder mindset: leave the codebase better than you found it. This means:

• Don’t die in perfection: While clean code and good practices are important, don’t let perfectionism block progress. It’s better to make something good than to block something perfect.
• Incremental improvement: Each contribution should improve the codebase, even if it’s not perfect. Future iterations can refine it further.
• Balance quality and velocity: Strive for quality, but recognize when “good enough” is sufficient to move forward. This aligns with clean code principles: readable, maintainable, and functional code is more valuable than theoretical perfection.

4. Commit Your Changes

Make regular commits as you work:

git commit -m "your commit message"

Conventional Commits (PR Titles)

To keep our changelogs automated and clean, we use the Conventional Commits format. However, we take a pragmatic approach:

• Required for PR Titles: The title of your Pull Request must follow the format (e.g., feat: add HID support). This is crucial because we Squash & Merge, and the PR title becomes the final commit message on the main branch.
• Optional for Local Commits: While working on your branch, you don’t need to strictly follow the format for every small commit. Use what makes you productive.

Common Types:

• feat:: A new feature.
• fix:: A bug fix.
• docs:: Documentation changes.
• refactor:: Code changes that don’t add features or fix bugs.
• chore:: Maintenance tasks (dependencies, build scripts).

See the CLA Guide for information about our Contributor License Agreement.

5. AI-Assisted Development

If you are using AI tools like Cursor or TaskMasterAI, please refer to our AI-Assisted Development Guide for a recommended workflow that maximizes efficiency while maintaining quality.

6. Push and Create a Pull Request

Push your branch to GitHub:

# Contributors push to their fork
git push origin feature/your-feature-name

# Maintainers push to the main repository
git push origin feature/your-feature-name

After pushing, go to the GitHub repository and create a Pull Request (PR) targeting the main branch.

7. Review and Merge

1. CI/CD: Wait for all automated checks to pass (Build, Lint, Tests, CLA).
2. Approval:
   • Contributors: Wait for a maintainer to review and approve your PR.
   • Maintainers: Request a review from another maintainer. Self-merging without approval is discouraged except for trivial fixes.
3. Merge: Once approved, the PR will be merged using Squash and merge.

Code Review Philosophy

Our review process follows the pathfinder mindset: we prefer approving good contributions over blocking perfect ones.

• Focus on improvement: The question isn’t “Is this perfect?” but rather “Is the codebase better than before?” If the answer is yes, the PR should generally be approved.
• Avoid perfectionism blockers: Don’t block PRs because they’re not perfect. If the code is functional, tested, and improves the project, it’s ready to merge.
• Constructive feedback: When suggesting improvements, frame them as enhancements rather than blockers. Minor issues can be addressed in follow-up PRs.
• Trust and iterate: We trust contributors to make good decisions. If something needs refinement, we can iterate on it in future contributions.

This approach ensures we maintain momentum while continuously improving code quality, aligning with clean code principles of maintainability and readability over theoretical perfection.