clarify that some parts of the contribution guidelines are (strongly) recommended, but not necessary

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,18 +1,19 @@
-See the contributing readme for more detailed guideline, please understand and accept them: https://github.com/Helium314/HeliBoard/blob/main/CONTRIBUTING.md
-tl;dr (you should still read the full list though):
-* make sure it's wanted
+See the contributing readme for more detailed guidelines: https://github.com/Helium314/HeliBoard/blob/main/CONTRIBUTING.md#guidelines
+tl;dr:
+necessary;
 * a single thing only
 * describe it properly
+recommended:
+* make changes optional
 * re-use existing mechanisms / code
 * low performance impact
 * make it a draft if you still want to work on it
-* no translations or dictionaries
 
 A good description and small scope ("single thing") massively help with reviewing. Don't be surprised when your PR gets closes if you clearly / repeatedly violate these parts of the guidelines.
 
 Further
 * When the PR contains "fixes" <issue number>, the related issue will be linked and automatically closed if the PR is merged (also works for other words like "fix", "resolve", "resolves", "closes", ...)
-* If you add a keyboard layout, make sure you also read https://github.com/Helium314/HeliBoard/blob/main/layouts.md#adding-new-layouts--languages
-* Please avoid force-pushing when doing changes unless you have a good reason. This way it's not possible to see which parts have changed since the previous state.
+* If you add a keyboard layout, best read https://github.com/Helium314/HeliBoard/blob/main/layouts.md#adding-new-layouts--languages
+* Please avoid force-pushing when doing requested changes. This way it's not possible to see which parts have changed since the previous state.
 
 <!-- (please remove the text above before submitting the PR) -->

CONTRIBUTING.md

@@ -6,31 +6,64 @@ 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 key inputs: `InputLogic`
+* Suggestions: `DictionaryFacilitatorImpl`, `Suggest`, `InputLogic`, and `SuggestionStripView` (in order from creation to display)
+* Forwarding entered text / keys to the app / text field: `RichInputConnection`
+* Receiving events and information from the app / text field: `LatinIME`
+
 # Guidelines
 
-HeliBoard is a complex application, when contributing, you must take a step back and make sure your contribution:
-- **Is actually wanted**. Best check related open issues before you start working on a PR. Issues with the [labels](https://github.com/Helium314/HeliBoard/labels) [_PR_](https://github.com/Helium314/HeliBoard/labels/PR) and [_contributor needed_](https://github.com/Helium314/HeliBoard/issues?q=label%3A%22contributor%20needed%22) (even closed ones) are accepted, but still it would be good if you announced that you are working on it, so we can discuss how changes are best implemented.
-  If there is no accepted issue related to your intended contribution, it's a good idea to open a new one (and of course getting one of "PR" or "contributor needed" labels) to avoid disappointment of the contribution not being accepted. For small changes or fixing obvious bugs this step is not necessary.
-- **Is only about a single thing**. Mixing unrelated or semi-related contributions into a single PR is hard to review and can get messy.
-- **Is finished or a draft**. When you keep changing the PR without reviewer's feedback, any attempt to review it is doomed and a waste of time. Better mark it as a draft in this case.
-- **Has a proper description**. What your contribution does is usually less obvious to reviewers than for yourself. A good description helps _a lot_ for understanding what is going on, and for separating wanted from unintended changes in behavior. Therefore the changes should be as described, not more and not less.
-- **Uses already in-place mechanism and take advantage of them**. In other terms, does not reinvent the wheel or uses shortcuts that could alter the consistency of the existing code. The contribution should only add as little complexity as necessary, the code is overly complicated already 😶.
-- **Has a low footprint**. Some parts of the code are executed very frequently, and the keyboard should stay responsive even on older devices.
-- **Does not bring any non-free code or proprietary binary blobs**. This also applies to code/binaries with unknown licenses. Make sure you do not introduce any closed-source library from Google.
-  If your contribution contains code that is not your own, provide a link to the source.
-- **Does not increase app size too much**. Just code changes or adding icons is not in issue, but e.g. large dependencies or adding more default dictionaries will not be accepted.
-- **Complies with the user privacy principle HeliBoard follows**.
+## Recommended
 
-A good description and small scope ("single thing") massively help with reviewing. Don't be surprised when your PR gets closes if you clearly / repeatedly violate these parts of the guidelines.
-If possible try to keep your changes contained, i.e. in few places as opposed to sprinkling them over many parts of the code. This helps with both review and maintainability of the app.
+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/Helium314/HeliBoard/labels) [_PR_](https://github.com/Helium314/HeliBoard/labels/PR) or [_contributor needed_](https://github.com/Helium314/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.
 
-Please leave dependency upgrades to the maintainers, unless it's an actual security issue.
+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.
 
-# Adding Layouts
+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.
+* 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
+
+## 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.
+- **No 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.
+
+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
 

layouts.md

@@ -1,9 +1,11 @@
-A compilation of information about the layout formats usable in this app.
+# A compilation of information about the layout formats usable in this app.
 
 There are two distinct formats:
 * the _simple_ format is a text file with one key label per line, and two consecutive line breaks indicating a switch to the next row, [example](app/src/main/assets/layouts/qwerty.txt)
 * the _json_ format taken from [FlorisBoard](https://github.com/florisboard/florisboard/blob/master/CONTRIBUTING.md#adding-the-layout), but only "normal" keys are supported (i.e. no action keys and similar), [example](app/src/main/assets/layouts/azerty.json)
 
+You can add both directly in the app, see the related [FAQ](https://github.com/Helium314/HeliBoard/wiki/Customization#layouts).
+
 ## General notes
 Adding too many keys or too long texts will make the keyboard look awkward or broken, and even crash the app under some specific conditions (popup keys are especially prone for this).
 There are some sanity checks when adding a layout to avoid such issues, but they do not cover all possible cases.