Merge branch 'docs' into 'master'

Docs: describe project priorities

See merge request Librem5/squeekboard!338

README.md

@@ -56,4 +56,4 @@ $ src/squeekboard
 Developing
 ----------
 
-See `HACKING.md`
+See [`docs/hacking.md`](docs/hacking.md) for this copy, or the [official documentation](https://developer.puri.sm/projects/squeekboard/) for the current release.

doc/hacking.md

@@ -3,10 +3,42 @@ Hacking
 
 This document describes the standards for modifying and maintaining the *squeekboard* project.
 
+Principles
+----------
+
+The project was built upon some guiding principles, which should be respected primarily by the maintainers, but also by contributors to avoid needlessly rejected changes.
+
+The overarching principle of *squeekboard* is to empower users.
+
+Software is primarily meant to solve problems of its users. Often in the quest to make software better, a hard distinction is made between the developer, who becomes the creator, and the user, who takes the role of the consumer, without direct influence on the software they use.
+This project aims to give users the power to make the software work for them by blurring the lines between users and developers.
+
+Nonwithstanding its current state, *squeekboard* must be structured in a way that provides users a gradual way to gain more experience and power to adjust it. It must be easy, in order of importance:
+
+- to use the software,
+- to modify its resources,
+- to change its behaviour,
+- to contribute upstream.
+
+To give an idea of what it means in practice, those are some examples of what has been important for *squeekboard* so far:
+
+- being quick and useable,
+- allowing local overrides of resources and config,
+- storing resources and config as editable, standard files,
+- having complete, up to date documentation of interfaces,
+- having an easy process of sending contributions,
+- adapting to to user's settings and constrains without overriding them,
+- avoiding compiling whenever possible,
+- making it easy to build,
+- having code that is [simple and obvious](https://www.python.org/dev/peps/pep-0020/),
+- having an easy process of testing and accepting contributions.
+
+You may notice that they are ordered roughly from "user-focused" to "maintainer-focused". While good properties are desired, sometimes they conflict, and maintainers should give additional weight to those benefitting the user compared to those benefitting regular contributors.
+
 Sending patches
 ---------------
 
-By submitting a change to this project, you agree to license it under the [GPL license version 3](./COPYING), or any later version. You also certify that your contribution fulfills the [Developer's Certificate of Origin 1.1](./dco.txt).
+By submitting a change to this project, you agree to license it under the [GPL license version 3](https://source.puri.sm/Librem5/squeekboard/blob/master/COPYING), or any later version. You also certify that your contribution fulfills the [Developer's Certificate of Origin 1.1](https://source.puri.sm/Librem5/squeekboard/blob/master/dco.txt).
 
 Development environment
 -----------------------
@@ -24,8 +56,7 @@ sudo apt-get -y install build-essential
 sudo apt-get -y build-dep .
 ```
 
-For an explicit list of dependencies check the `Build-Depends` entry in the
+For an explicit list of dependencies check the `Build-Depends` entry in the [`debian/control`](https://source.puri.sm/Librem5/squeekboard/blob/master/debian/control) file.
-[`debian/control`](./debian/control) file.
 
 Testing
 -------

doc/index.md

@@ -5,17 +5,23 @@ Contents
 --------
 
 * [Tutorial](tutorial.md)
+* [Contributing](hacking.md)
 
 Introduction
 ------------
 
-Squeekboard is the on-screen keyboard for the Librem 5 phone. For more information, look at the [README](https://source.puri.sm/Librem5/squeekboard/blob/master/README.md).
+Squeekboard is the on-screen keyboard for the Librem 5 phone. For information about building, look at the [README](https://source.puri.sm/Librem5/squeekboard/blob/master/README.md).
 
 Layouts
 -------
 
-Squeekboard allows user-provided keyboard layouts. They can be created without recompiling the keyboard code. The [tutorial](/tutorial.md) explains the process in detail.
+Squeekboard allows user-provided keyboard layouts. They can be created without recompiling the keyboard code. The [tutorial](tutorial.md) explains the process in detail.
 
 Layouts are created using a text-based format, based on YAML.
 
 TODO: Provide a description of the format.
+
+Contributions
+-------------
+
+Anyone is free to modify *squeekboard*. See the [contributing document](hacking.md).

doc/tutorial.md

@@ -31,7 +31,7 @@ So at least I will try to start writing a short how-to here and edit this post a
 **Running squeekboard**
 
 * Follow these instructions to run squeekboard: [https://source.puri.sm/Librem5/squeekboard/blob/master/README.md#running ](https://source.puri.sm/Librem5/squeekboard/blob/master/README.md#running)
-* Additionally take a look at https://source.puri.sm/Librem5/squeekboard/blob/master/HACKING.md#testing
+* Additionally take a look at the contribution document for [testing info](HACKING.md#testing)
 * You can either test it locally on your Linux system or use the [QEMU Librem 5 image ](https://developer.puri.sm/Librem5/Development_Environment/Boards/emulators.html)
 * To test squeekboard locally, you need phoc. Either compile that from the sources as well or use the CI repository ci.puri.sm for Debian based systems:
   `deb [arch=amd64] http://ci.puri.sm/ scratch librem5`