Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (53 loc) · 4.82 KB

CONTRIBUTING.md

File metadata and controls

73 lines (53 loc) · 4.82 KB

Contributing to QuickBars

First off, thank you for considering contributing to QuickBars!

Please take a moment to review these guidelines to make the contribution process effective for everyone.

⚠️ Rules of Engagement

To keep this project manageable for a solo developer/student, please adhere to these strict rules:

  • Language: All issues, pull requests, and discussions must be in English.
  • Completeness: You must fill out all sections of the provided templates.
  • Automatic Closure: Issues or discussions that are not in English or are incomplete will be closed immediately.
  • Respect the Maintainer: This project is managed by Omri in his spare time. Help me help you by being clear and professional.

:octocat: The Contribution Workflow

To ensure that changes align with the project's goals and architecture, please follow our refined workflow:

  1. Start a Discussion: Before writing any code, start a new discussion.
    • Use the Ideas category for new features.
    • Use the Q&A category if you aren't sure if something is a bug or just a configuration issue.
  2. Consensus & Approval: Wait for the community and maintainers to chime in. Once we agree on the approach, a maintainer will convert the discussion into a formal Issue.
  3. Fork & Branch: Once the official issue is created and assigned, fork the repository. Create a new descriptive branch (e.g., feature/new-entity-support or fix/overlay-flicker).
  4. Local Development: Set up your environment (see Local Setup below).
  5. Manual Testing: Verify your changes on a real device (see Testing below).
  6. Submit a Pull Request: Submit your PR referencing the original issue (e.g., "Fixes #12"). Please write clear, descriptive commit messages.

🧰 Local Setup

You can build and test QuickBars without access to production API keys or private signing certificates.

1. Setup Global Properties

To prevent the build from failing, you must provide placeholder values for the required variables in your global gradle.properties file.

  • Windows: C:\Users\<YourName>\.gradle\gradle.properties
  • Mac/Linux: ~/.gradle/gradle.properties

Add the following lines to that file:

REVENUECAT_API_KEY="dummy_key"
HA_QUICKBARS_KEYSTORE_FILE="not_needed_for_debug"
HA_QUICKBARS_KEYSTORE_PASSWORD="dummy"
HA_QUICKBARS_KEY_ALIAS="dummy"
HA_QUICKBARS_KEY_PASSWORD="dummy"

2. Build Variant

In Android Studio, ensure you are using the debug build variant. This variant uses the standard Android debug key and ignores the production signing configuration.

🎨 Code Style

To keep the codebase clean and readable, please ensure your code follows standard Android Kotlin styling conventions. Before submitting a PR, run the standard Android Studio auto-formatter (Ctrl+Alt+L on Windows, Cmd+Option+L on Mac) on any files you have modified.

🧪 Testing & Quality Assurance

Because QuickBars interacts with system-level overlays and physical remote key interception, testing is currently a manual process.

The Current Testing Standard:

Hardware: We test on real Android TV hardware, such as the Nvidia Shield or Chromecast with Google TV, to ensure performance and compatibility.

Manual Checks: We make sure the feature/fix we implemented is working as expected, and that any other feature it may have affected was not affected at all. This requires familiarity with the codebase. If large changes were made, especially ones that affect data storage and persistance - then the following test is required:

  1. Run the main (public version) branch on your Android TV device using a debug build, and set it up normally (connect to HA, create a QuickBar with some entities).
  2. Run your new branch on the same device (simulating a software update).
  3. Make sure no data was corrupted during this update, and test all other functionality normally.

🧠 AI Use in Contributions

AI use in PRs is allowed, but all code AI writes must be 100% understandable and familiar to the person making the PR, as if he wrote it himself, as well as meet the project's code and testing standards.

🚀 Help Wanted: CI/CD & Automation

Manual testing is the current standard for this project, but I am very open to improvements. If you have experience with automated UI testing for Android TV or ideas for a CI/CD pipeline, please start a thread in Discussions! I would love to discuss how to make the project more robust.

📜 License

By contributing to QuickBars, you agree that your contributions will be licensed under the GNU General Public License v3.0 (GPLv3).