|
1 | 1 | # Contributing to Askimo |
2 | 2 |
|
3 | | -Thanks for considering a contribution! We welcome issues, feature requests, and pull requests. |
4 | | -To keep contributions clear and legally safe for everyone, Askimo uses the Developer Certificate of Origin (DCO). |
| 3 | +Thanks for considering a contribution! We welcome bug reports, feature requests, and pull requests. |
5 | 4 |
|
6 | | -# 📝 Developer Certificate of Origin (DCO) |
| 5 | +## Ways to Contribute |
7 | 6 |
|
8 | | -The DCO is a lightweight alternative to a Contributor License Agreement (CLA). |
9 | | -By signing off your commits, you certify that: |
| 7 | +- **Bug reports** — open an issue with steps to reproduce, expected vs. actual behavior, and your OS/version |
| 8 | +- **Feature requests** — open an issue describing the use case and why it fits the project |
| 9 | +- **Code contributions** — pick up an open issue (look for `good first issue` labels) or propose something new |
10 | 10 |
|
11 | | -> The contribution is your original work, or you have the right to submit it under the project’s license, and you |
12 | | -> agree it can be distributed under the AGPLv3 License. |
| 11 | +Before opening a new issue, please search existing ones to avoid duplicates. |
13 | 12 |
|
14 | | -The full text is available here: https://developercertificate.org/ |
| 13 | +## Development Setup |
15 | 14 |
|
16 | | -## ✅ How to sign off a commit |
| 15 | +Requirements: **JDK 21+**, **Gradle** (wrapper included). |
17 | 16 |
|
18 | | -When you make a commit, add the -s flag: |
| 17 | +```bash |
| 18 | +# Clone your fork |
| 19 | +git clone https://github.com/<your-username>/askimo.git |
| 20 | +cd askimo |
| 21 | + |
| 22 | +# Build everything |
| 23 | +./gradlew build |
| 24 | + |
| 25 | +# Run the desktop app |
| 26 | +./gradlew :desktop:run |
| 27 | +``` |
| 28 | + |
| 29 | +See [`AGENTS.md`](AGENTS.md) for a full breakdown of the module structure and key files. |
| 30 | + |
| 31 | +## Code Style |
| 32 | + |
| 33 | +Askimo uses **Spotless** (ktlint) and **Detekt** to enforce consistent formatting and static analysis. Run these before every commit: |
| 34 | + |
| 35 | +```bash |
| 36 | +# Auto-fix formatting |
| 37 | +./gradlew spotlessApply |
| 38 | + |
| 39 | +# Check only (what CI runs) |
| 40 | +./gradlew spotlessCheck |
| 41 | + |
| 42 | +# Static analysis |
| 43 | +./gradlew detekt |
| 44 | +``` |
| 45 | + |
| 46 | +### Optional: install the pre-commit hook |
| 47 | + |
| 48 | +A pre-commit hook is provided that runs `spotlessApply` and `detekt` automatically on every `git commit`: |
19 | 49 |
|
20 | 50 | ```bash |
21 | | -git commit -s -m "Add new feature" |
| 51 | +sh tools/git/pre-commit |
22 | 52 | ``` |
23 | 53 |
|
24 | | -This appends a Signed-off-by line to your commit message, e.g.: |
| 54 | +This installs the hook into `.git/hooks/pre-commit`. You only need to run it once per clone. |
| 55 | + |
| 56 | +Key style rules enforced by ktlint: |
| 57 | +- 4-space indentation |
| 58 | +- No wildcard imports |
| 59 | +- Trailing newline on all files |
| 60 | +- All source files must include the license header (`HEADER-SRC`) |
| 61 | + |
| 62 | +PRs that fail `spotlessCheck` will not be merged. |
| 63 | + |
| 64 | +## Running Tests |
25 | 65 |
|
26 | 66 | ```bash |
| 67 | +# Run all tests |
| 68 | +./gradlew test |
| 69 | + |
| 70 | +# Run tests for a specific module |
| 71 | +./gradlew :shared:test |
| 72 | +``` |
| 73 | + |
| 74 | +Please make sure all tests pass locally before opening a PR. If you are adding new functionality, include tests for it. |
| 75 | + |
| 76 | +## Branch & PR Workflow |
| 77 | + |
| 78 | +1. **Fork** the repository and create a branch from `main`: |
| 79 | + ```bash |
| 80 | + git checkout -b feat/my-feature |
| 81 | + ``` |
| 82 | +2. Make your changes, following the code style rules above. |
| 83 | +3. Run `./gradlew spotlessApply` and `./gradlew test`. |
| 84 | +4. Commit with a sign-off (see [DCO](#-developer-certificate-of-origin-dco) below). |
| 85 | +5. Push your branch and open a Pull Request against `main`. |
| 86 | +6. Fill in the PR description: what changed, why, and how to test it. |
| 87 | + |
| 88 | +Keep PRs focused — one feature or fix per PR makes review faster. |
| 89 | + |
| 90 | +## Commit Messages |
| 91 | + |
| 92 | +We follow **Conventional Commits**: |
| 93 | + |
| 94 | +``` |
| 95 | +<type>(<scope>): <short description> |
| 96 | +
|
| 97 | +[optional body] |
| 98 | +
|
27 | 99 | Signed-off-by: Your Name <your.email@example.com> |
28 | 100 | ``` |
29 | 101 |
|
30 | | -## 🔄 Amending a commit to add a sign-off |
| 102 | +Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`. |
| 103 | + |
| 104 | +Examples: |
| 105 | +``` |
| 106 | +feat(desktop): add DeepSeek provider support |
| 107 | +fix(desktop): handle missing API key gracefully |
| 108 | +docs: update CONTRIBUTING with test instructions |
| 109 | +``` |
| 110 | + |
| 111 | +## 📝 Developer Certificate of Origin (DCO) |
| 112 | + |
| 113 | +The DCO is a lightweight alternative to a CLA. By signing off your commits, you certify that: |
| 114 | + |
| 115 | +> The contribution is your original work, or you have the right to submit it under the project's |
| 116 | +> license, and you agree it can be distributed under the AGPLv3 License. |
| 117 | +
|
| 118 | +Full text: https://developercertificate.org/ |
| 119 | + |
| 120 | +### Signing off a commit |
| 121 | + |
| 122 | +Add the `-s` flag when committing: |
31 | 123 |
|
32 | | -If you forgot to sign off: |
| 124 | +```bash |
| 125 | +git commit -s -m "feat: add new feature" |
| 126 | +``` |
| 127 | + |
| 128 | +This appends a `Signed-off-by` line to your commit message: |
| 129 | + |
| 130 | +``` |
| 131 | +Signed-off-by: Your Name <your.email@example.com> |
| 132 | +``` |
| 133 | + |
| 134 | +> **Note:** `-s` (DCO sign-off) is different from `-S` (GPG cryptographic signing). Only `-s` is required here. |
| 135 | +
|
| 136 | +### Forgot to sign off? |
| 137 | + |
| 138 | +Single commit: |
33 | 139 | ```bash |
34 | 140 | git commit --amend -s |
35 | 141 | git push --force-with-lease |
36 | 142 | ``` |
37 | 143 |
|
38 | | -For multiple commits: |
| 144 | +Multiple commits: |
39 | 145 | ```bash |
40 | 146 | git rebase --exec 'git commit --amend -s --no-edit' main |
41 | 147 | git push --force-with-lease |
42 | 148 | ``` |
43 | 149 |
|
44 | | -## 🤖 Enforcing DCO |
| 150 | +The **DCO GitHub App** automatically checks every commit in a PR. PRs without sign-offs will be blocked until all commits are signed. |
| 151 | + |
| 152 | +## License |
| 153 | + |
| 154 | +By contributing to Askimo, you agree that your contributions will be licensed under the |
| 155 | +[GNU AGPLv3 License](LICENSE). |
| 156 | + |
| 157 | +## Questions? |
45 | 158 |
|
46 | | -To make sure every PR is compliant, we use the **DCO GitHub App**. |
47 | | -It automatically checks for the `Signed-off-by` line on each commit. |
48 | | -PRs without it will be flagged until all commits are signed. |
| 159 | +Open a [GitHub Discussion](https://github.com/askimo-ai/askimo/discussions) or file an issue — we're happy to help. |
0 commit comments