### CONTRIBUTING # Getting Started HeliBoard project is based on Gradle and Android Gradle Plugin. To get started, you can install [Android Studio](https://developer.android.com/studio), and import project 'from Version Control / Git / Github' by providing this git repository [URL](https://github.com/HeliBorg/HeliBoard) (or git SSH [URL](git@github.com:Helium314/heliboard.git)). Of course you can also use any other compatible IDE, or work with text editor and command line. Once everything is up correctly, you're ready to go! If you have difficulties implementing some functionality, you're welcome to ask for help. No one will write the code for you, but often other contributors can give you very useful hints. # About the Code HeliBoard is based on AOSP keyboard, and in many places still contains mostly the original code. There are some extensions, and some parts have been replaced completely. When working on this app, you will likely notice its rather large size, and quite different code styles and often ancient comments and _TODO_s, where the latter are typically untouched since AOSP times. Unfortunately a lot of the old code is hard to read or to fully understand with all of its intended (and unintended) consequences. Some hints for finding what you're looking for: * Layouts: stored in `layouts` folder in assets, interpreted by `KeyboardParser` and `TextKeyData` * Popups: either on layouts, or in `locale_key_texts` (mostly letter variations for specific languages that are not dependent on layout) * Touch and swipe input handling: `PointerTracker` * Handling of keycode / text inputs: `InputLogic` * chain: `PointerTracker` -> `KeyboardActionListenerImpl` -> `LatinIME` -> `InputLogic` * Suggestions: `DictionaryFacilitatorImpl`, `Suggest`, `InputLogic`, and `SuggestionStripView` (in order from creation to display, omitting the native library) * Communication with the app / text field (inputs, reading current text): `RichInputConnection` * Receiving events and information from the app / text field: `LatinIME` * Settings are in `SettingsValues`, with some functionality in `Settings` and the default values in `Default` # Guidelines Note that the maintainer only has very limited time, and thus review might take a while. This especially applies to large PRs (hundreds of lines), which recently started to become more common. Sorry, but there is simply not enough time to review everything. What's more likely to be reviewed soon: * Simple changes (but depends on what effect they have, as in some places it's easy to introduce unintended changes) * Wanted / accepted changes (labels [_PR_](https://github.com/HeliBorg/HeliBoard/labels/PR), [_contributor needed_](https://github.com/HeliBorg/HeliBoard/issues?q=label%3A%22contributor%20needed%22), [_help wanted_](https://github.com/HeliBorg/HeliBoard/labels/help%20wanted)) * Changes where the hard work is mostly investigation / research rather than coding * e.g. compiling text lists to dictionaries, customizable icons / key backgrounds, OnePlus disabling keyboard on reboot, ... What will likely take some time (depends very much on how much other stuff is coming in): * Large changes (especially when connected to rather niche functionality) * Changes in code that is prone to introducing unintended effects * `InputLogic`, `Suggest`, `RichInputConnection` are especially dangerous here, and also hard to test (behavior may depend on app and possibly OS version) ## Recommended If you want to contribute, it's a good idea to make sure your idea is actually wanted in HeliBoard. Best check related issues before you start working on a PR. If the issue has the [labels](https://github.com/HeliBorg/HeliBoard/labels) [_PR_](https://github.com/HeliBorg/HeliBoard/labels/PR) or [_contributor needed_](https://github.com/HeliBorg/HeliBoard/issues?q=label%3A%22contributor%20needed%22) (even closed ones), contributions are wanted. If you don't find a related issue, it's recommended to open one, but ultimately it's your choice. Asking before starting a PR may help you for getting pointers to potentially relevant code, and deciding how to implement your desired changes. HeliBoard is a complex application and used by users with a large variety of opinions on how things should be. When contributing to the app, please: * Be careful when modifying core components, as it's easy to trigger unintended consequences * When introducing a feature or change that might not be wanted by everyone, make it optional * Keep code simple where possible. Complex code is harder to review and to maintain, so the complexity should also add a clear benefit * Avoid noticeable performance impact. Some parts of the code are executed very frequently, and the keyboard should stay responsive even on older devices. * Try making use of in-place mechanisms instead of re-inventing the wheel. Your contribution should only add as much complexity as necessary, the code is overly complicated already 😶. * Keep your changes to few places, as opposed to sprinkling them over many parts of the code. This helps with keeping down complexity during review, and with maintainability of the app. * Make a draft PR when you intend to still work on it. Submitting an unfinished PR can be a good idea when you're not sure how to best continue and would like some comments. * When you fix a bug without opening an issue, please provide a way to reproduce the bug (see [bug report template](.github/ISSUE_TEMPLATE/bug_report.md)) * Noticeable adjustments (keyboard UI, default layouts, ...) should either provide a benefit for everyone, or be optional. * If your contribution contains code that is not your own, provide a link to the source * This is especially relevant to be sure the code's license is compatible to HeliBoard's GPL3 * Note that with LLM generated PRs you might add code with an incompatible license. Better make sure the LLM you're using is trained only with GPL3 compatible code. Further things to consider (though irrelevant for most PRs): * APK size: * Large increases should be discussed first, and will only be added when it's considered worth the increase for a majority of users. It might be possible to avoid size increase by importing optional parts, like it's done for dictionaries. * Small increases like when adding code or layouts are never an issue * Do not add proprietary code or binary blobs. If it turns out to be necessary for a feature you want to add, it might be acceptable when the user opts in and imports those parts, like it's done for glide typing. * Privacy: Only relevant when adding some form of communication with other apps. Internet permission will not be added. ## Necessary Some parts of the guidelines are necessary to fulfill for facilitating code review. It doesn't need to be perfect from the start, but consider it for your future PRs when you're reminded of these guidelines. Note that the larger / more complex your PR is, the more relevant these guidelines are. Your PR should: - **Be only about a single thing**. Mixing unrelated or semi-related contributions into a single PR is hard to review and can get messy. As a general rule: if one part doesn't need the other one(s), it should be separate PRs. If one feature builds on top of another one, but the base is usable on its own, do a PR for the base and then a follow-up once it's merged. - **Have a proper description**. A good description helps _a lot_ for understanding what you intend to achieve with the changes, and for understanding the code. This is relevant for separating wanted from unintended changes in behavior during review. - **Not contain translations**. Translations should be done using [Weblate](https://translate.codeberg.org/projects/heliboard/). Exception is when you add new resource strings, those can be added right away. - **Not be LLM generated**. LLMs enable contributors to quickly generate code that often is bulky and contains parts that are hard to understand. When the you do not understand the code, it's not possible to discuss such parts. See also [AI_USAGE.md](AI_USAGE.md). - **Not contain LLM generated discussion / description**. LLMs typically generate verbose and useless descriptions. Please save us some time and write it yourself, otherwise actual discussion is impossible. Please leave dependency upgrades to the maintainers, unless you state a good reason why they should be done now. # Adding / Adjusting Layouts See [layouts.md](layouts.md#adding-new-layouts--languages) for how to add new layouts to the app. Please stay in line with other layouts regarding the popup keys. When editing existing layouts, please consider that people should should still get what they're used to. In case of doubt it might be better to add a new layout instead of overhauling existing layouts. `locale_key_texts` files should only contain letters that are actually part of the language, with exception of the optional `more_popups_<...>.txt` files. # Update Emojis See make-emoji-keys tool [README](tools/make-emoji-keys/README.md). # Translations Translations can be added using [Weblate](https://translate.codeberg.org/projects/heliboard/). You will need an account to update translations and add languages. Add the language you want to translate to in Languages -> Manage translated languages in the top menu bar. Updating translations in a PR will not be accepted, as it may cause conflicts with Weblate translations. # Dictionaries No new dictionaries will be added to this app. Please submit dictionaries and the wordlist to the [dictionaries repository](https://codeberg.org/Helium314/aosp-dictionaries) --- ### README # HeliBoard HeliBoard is a privacy-conscious and customizable open-source keyboard, based on AOSP / OpenBoard. Does not use internet permission, and thus is 100% offline. [Get it on F-Droid](https://f-droid.org/packages/helium314.keyboard/) [Get APK from GitHub](https://github.com/HeliBorg/HeliBoard/releases/latest) [Get it on IzzyOnDroid](https://apt.izzysoft.de/fdroid/index/apk/helium314.keyboard) ## Table of Contents - [Features](#features) - [Contributing](#contributing-) * [Reporting Issues](#reporting-issues) * [Translations](#translations) * [To Community](#to-community) * [Code Contribution](CONTRIBUTING.md) - [Links](#links) - [License](#license) - [Credits](#credits) * [Funding](#funding) # Features For [FAQ](https://github.com/HeliBorg/HeliBoard/wiki/FAQ), [hidden features](https://github.com/HeliBorg/HeliBoard/wiki/9.-Hidden-features) and more information about the app and features, please visit the [wiki](https://github.com/HeliBorg/HeliBoard/wiki) # Contributing ❤ ## Reporting Issues Whether you encountered a bug, or want to see a new feature in HeliBoard, you can contribute to the project by opening a new issue [here](https://github.com/HeliBorg/HeliBoard/issues). Your help is always welcome! Before opening a new issue, be sure to check the following: - **Does the issue already exist?** Make sure a similar issue has not been reported by browsing [existing issues](https://github.com/HeliBorg/HeliBoard/issues?q=). Please search open and closed issues. In case of feature requests you could also check the [FAQ](https://github.com/HeliBorg/HeliBoard/wiki/FAQ) and [hidden features](https://github.com/HeliBorg/HeliBoard/wiki/9.-Hidden-features). - **Is the issue still relevant?** Make sure your issue is not already fixed in the latest version of HeliBoard. - **Is it a single topic?** If you want to suggest multiple things, open multiple issues. - **Did you use the issue template?** It is important to make life of our kind contributors easier by avoiding issues that miss key information to their resolution. - **Is it written by a human?** Do not use LLMs or similar to generate issues. Having LLMs help with translation or similar is acceptable, but must be disclosed. See also [AI_USAGE.md](AI_USAGE.md) Note that issues that that ignore part of the issue template will likely get treated with very low priority, as often they are needlessly hard to read or understand (e.g. huge screenshots, not providing a proper description, or addressing multiple topics). Blatant violation of the guidelines may result in the issue getting closed. If you're interested, you can read the following useful text about effective bug reporting (a bit longer read): https://www.chiark.greenend.org.uk/~sgtatham/bugs.html ## Translations Translations can be added using [Weblate](https://translate.codeberg.org/projects/heliboard/). You will need an account to update translations and add languages. Add the language you want to translate to in Languages -> Manage translated languages in the top menu bar. Updating translations in a PR will not be accepted, as it may cause conflicts with Weblate translations. Some notes on translations * when translating metadata, translating the changelogs is rather useless. It's available as it was requested by translators. * the `hidden_features_message` is horrible to translate with Weblate, and serves little benefit as it's just a copy of what's already in the wiki: https://github.com/HeliBorg/HeliBoard/wiki/9.-Hidden-features. It's been made available in the app on user request/contribution. ## To Community There is the [discussions on GitHub](https://github.com/HeliBorg/HeliBoard/discussions), or if you prefer a more open network there is [Lemmy](https://lemmy.world/c/Heliboard). You can share your themes, layouts and dictionaries with other people: * Themes can be saved and loaded using the menu on top-right in the _adjust colors_ screen * you can share custom colors in a separate [discussion section](https://github.com/HeliBorg/HeliBoard/discussions/categories/custom-colors) * there are theme collections available at [Star-Trowa/heliboard-themes](https://github.com/Star-Trowa/heliboard-themes) and [PickleHik3/droid-tings](https://github.com/PickleHik3/droid-tings) * Custom keyboard layouts are text files whose content you can edit, copy and share * this applies to main keyboard layouts and to special layouts adjustable in advanced settings * see [layouts.md](layouts.md) for details * you can share custom layouts in a separate [discussion section](https://github.com/HeliBorg/HeliBoard/discussions/categories/custom-layout) * [Roccobot's Layout Maker](https://roccobot.github.io/HeliBoard-RLM/) is a browser-based editor for json layout files * Creating dictionaries is a little more work * first you will need a wordlist, as described [here](https://codeberg.org/Helium314/aosp-dictionaries/src/branch/main/wordlists/sample.combined) and in the repository readme * the you need to compile the dictionary using [external tools](https://github.com/remi0s/aosp-dictionary-tools) * the resulting file (and ideally the wordlist too) can be shared with other users * note that there will not be any further dictionaries added to this app, but you can add dictionaries to the [dictionaries repository](https://codeberg.org/Helium314/aosp-dictionaries) ## Code Contribution See [Contribution Guidelines](CONTRIBUTING.md) # Links * Info * [Wiki](https://github.com/HeliBorg/HeliBoard/wiki), including FAQ, help on customizing layouts, and gesture data gathering * [Layout documentation](layouts.md) (more technical info regarding layout customization) * [For creating custom dictionaries](https://codeberg.org/Helium314/aosp-dictionaries#wordlist-information) (see also top of the linked readme) * Community * [Lemmy](https://lemmy.world/c/Heliboard) * [Reddit](https://www.reddit.com/r/HeliBoard) * GitHub [discussions](https://github.com/HeliBorg/HeliBoard/discussions) * Other * [Translations](https://translate.codeberg.org/projects/heliboard/) * [Dictionaries](https://codeberg.org/Helium314/aosp-dictionaries) * [k3lp](https://codeberg.org/k3lp/k3lp) is a WIP library for keyboard layout parsing that will be implemented in HeliBoard when ready (created by [FlorisBoard](https://github.com/florisboard/florisboard/) maintainers) * [swipe-o-scope](https://codeberg.org/eclexic/swipe-o-scope) for visualizing gesture data as created when using gesture data gathering # License HeliBoard (as a fork of OpenBoard) is licensed under GNU General Public License v3.0. > Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. See repo's [LICENSE](/LICENSE) file. Since the app is based on Apache 2.0 licensed AOSP Keyboard, an [Apache 2.0](LICENSE-Apache-2.0) license file is provided. The icon is licensed under [Creative Commons BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). A [license file](LICENSE-CC-BY-SA-4.0) is also included. # Credits - Icon by [Fabian OvrWrt](https://github.com/FabianOvrWrt) with contributions from [The Eclectic Dyslexic](https://github.com/the-eclectic-dyslexic) - [OpenBoard](https://github.com/openboard-team/openboard) - [AOSP Keyboard](https://android.googlesource.com/platform/packages/inputmethods/LatinIME/) - [LineageOS](https://review.lineageos.org/admin/repos/LineageOS/android_packages_inputmethods_LatinIME) - [Simple Keyboard](https://github.com/rkkr/simple-keyboard) - [Indic Keyboard](https://gitlab.com/indicproject/indic-keyboard) - [FlorisBoard](https://github.com/florisboard/florisboard/) - Our [contributors](https://github.com/HeliBorg/HeliBoard/graphs/contributors) ## Funding This project is funded through [NGI Mobifree Fund](https://nlnet.nl/mobifree), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/GestureTyping). [NLnet foundation logo](https://nlnet.nl) Further the project benefits from donations provided by many users (thank you all!). ---