From 7eb5c6d466737989d39ba1a542abdcd333623c51 Mon Sep 17 00:00:00 2001 From: Dorota Czaplejewicz Date: Fri, 28 Feb 2020 13:26:09 +0000 Subject: [PATCH 1/2] docs: Add the guiding principle --- HACKING.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/HACKING.md b/HACKING.md index 4c037d0f..4b4e2f45 100644 --- a/HACKING.md +++ b/HACKING.md @@ -3,6 +3,38 @@ 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 --------------- From 8f3d0103493f76a8270c7965c63dd72d0478aa4c Mon Sep 17 00:00:00 2001 From: Dorota Czaplejewicz Date: Fri, 28 Feb 2020 13:30:43 +0000 Subject: [PATCH 2/2] hacking: Move into docs/ --- README.md | 2 +- HACKING.md => doc/hacking.md | 5 ++--- doc/index.md | 10 ++++++++-- doc/tutorial.md | 2 +- 4 files changed, 12 insertions(+), 7 deletions(-) rename HACKING.md => doc/hacking.md (94%) diff --git a/README.md b/README.md index afb92e21..756b4c7e 100644 --- a/README.md +++ b/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. diff --git a/HACKING.md b/doc/hacking.md similarity index 94% rename from HACKING.md rename to doc/hacking.md index 4b4e2f45..7b016f63 100644 --- a/HACKING.md +++ b/doc/hacking.md @@ -38,7 +38,7 @@ You may notice that they are ordered roughly from "user-focused" to "maintainer- 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 ----------------------- @@ -56,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 -[`debian/control`](./debian/control) file. +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. Testing ------- diff --git a/doc/index.md b/doc/index.md index 065d7a0c..0c73eecf 100644 --- a/doc/index.md +++ b/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). diff --git a/doc/tutorial.md b/doc/tutorial.md index 716b8dda..d97c6173 100644 --- a/doc/tutorial.md +++ b/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`