Files
etchdroid/CONTRIBUTING.md

68 lines
3.8 KiB
Markdown

# Contributing to EtchDroid
Thanks for taking the time to contribute! To maintain a high standard of code quality and a clean project history, please follow these guidelines.
## 🤝 Code of Conduct
EtchDroid follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct/). In short: be helpful, don't take code critiques personally, and **Don't Be A Dick™️**.
---
## 🐛 Reporting Bugs & Suggestions
* **Check for duplicates:** Ensure the issue hasn't been reported or suggested already.
* **Troubleshoot hardware:** Many "bugs" are actually bad cables or sleep settings. Try writing while the device is on a table with the screen kept on.
* **Use the templates:** Fill out the requested information in the issue template so the bug can be reproduced.
* **Scope:** Features requiring root privileges or those outside the app's scope will not be accepted.
---
## 🌍 Translating
* **Weblate Only:** All translations must be done via [Weblate](https://hosted.weblate.org/engage/etchdroid/). **Pull requests for string files will be rejected.**
* **Credits:** After translating, you may send a PR to update [`about.xml`](https://github.com/EtchDroid/EtchDroid/blob/main/app/src/main/res/xml/about.xml) to be credited in the app.
---
## 🛠 Development Workflow
### 1. Linear History (No Merge Commits)
We use a **rebase-only workflow**. Your branch must be rebased onto the latest `main` branch.
* **Do:** Use `git rebase main`.
* **Do:** Use `git rebase -i main` to clean up your history.
* **Don't:** Use `git merge main` or the GitHub "Resolve conflicts" button.
### 2. Atomic & Concise Commits
* **One Thing Per Commit:** Each commit should perform one logical task.
* **Small PRs:** If you are fixing multiple unrelated bugs, submit them as separate PRs.
* **No "Fixup" History:** Do not include commits that revert or fix changes introduced earlier in the same PR. Use `git commit --amend` or `git rebase -i` to squash mistakes before submitting.
### 3. Separate Cleanup from Logic
**Do not lump stylistic/formatting/cleanup changes into functional commits.**
* If you need to reformat code, do it in a dedicated commit (or separate PR).
* **Rule of thumb:** Do not fix what isn't broken unless it's necessary for your change.
### 4. Commit Messages
Be descriptive. We suggest (but don't require) the [Conventional Commits](https://www.conventionalcommits.org/) format (e.g., `feat(ui): add progress bar`).
---
## 💻 Coding Standards & Testing
* **Formatting:** Use default Android Studio formatting (`Ctrl+Alt+L`).
* **Clean Code:** Use constants instead of magic numbers and write self-documenting code. **Comments should explain *why*, not *what***.
* **Testing:**
* Run unit tests via Android Studio or `./gradlew test`.
* Manually verify your changes by running the app and flashing a test image.
* **End-to-End Tests:** We use Appium for E2E tests. You are encouraged to run them locally:
* **Linux:** (probably macOS too, untested) You can run the tests using a Bliss OS VM. See `appium-tests/README.md` for setup instructions.
* **Physical Device:** Connect a device via ADB and plug in a USB drive (at least 2GB).
* **Note:** On physical devices, skip QEMU tests using `uv run pytest -m "not qemu" -sv`. The tests **will fully erase** the connected USB drive since random data will be written to it.
---
## 🚀 Pull Request Process
1. **Discuss Big Changes:** For significant features, open an issue first to ensure it aligns with project goals.
2. **Self-Review:** Review your own code for typos or leftover debug logs before submitting.
3. **Be Professional:** If changes are requested, explain your reasoning if you disagree. Disagreements are fine; the goal is to find a compromise.
By contributing, you agree that your code will be licensed under the project's [GPLv3 License](LICENSE).