Add and enforce a style guide (toltec-dev#96)

* Add and enforce a style guide (fixes toltec-dev#95)

* Define an automatically-enforceable style guide by adding an
.editorconfig file (configures shfmt).
* Replace Vim modelines by Bash shebangs so that shfmt can detect all
shell scripts as such, and update docs/package.md accordingly.
* Add `make lint` target to run `shellcheck` and report errors.
* Add `make format` target to run `shfmt` and report errors.
* Add `make format-fix` target to run `shfmt` and automatically fix
errors.
* Fix existing formatting errors.
* Check format and lint conformity in the `pr` workflow.
* Mention the style guide in docs/contributing.md

Co-authored-by: raisjn <[email protected]>

Author: matteodelabre

.editorconfig

@@ -0,0 +1,24 @@
+# Style guide for Toltec
+# See <https://editorconfig.org/>
+root = true
+
+[*]
+# Options that apply to all source files
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 80
+
+# Options for shell scripts
+shell_variant = bash
+binary_next_line = true
+switch_case_indent = true
+space_redirects = true
+keep_padding = false
+function_next_line = false
+
+[build/**]
+ignore = true

.github/workflows/pr.yml

@@ -2,19 +2,55 @@ name: pr
 on:
     pull_request
 jobs:
-    pr:
-        name: Check that a pull request correctly builds
+    lint:
+        name: Check that it conforms to the style guide
         runs-on: ubuntu-latest
         steps:
             - name: Checkout the Git repository
               uses: actions/checkout@v2
             - name: Install missing tools
               run: |
-                sudo apt-get install bsdtar tree
+                install_dir=/usr/local/bin
+
+                # Install shfmt
+                shfmt_version=v3.1.2
+                shfmt_checksum=c5794c1ac081f0028d60317454fe388068ab5af7740a83e393515170a7157dce
+                sudo curl --location --silent --fail --tlsv1.2 --proto '=https' \
+                    --output "$install_dir"/shfmt \
+                    https://github.com/mvdan/sh/releases/download/"$shfmt_version"/shfmt_"$shfmt_version"_linux_amd64
+                sha256sum -c <(echo "$shfmt_checksum $install_dir/shfmt") > /dev/null 2>&1
+                sudo chmod a+x "$install_dir"/shfmt
+
+                # Install Shellcheck (Ubuntu’s version is too old)
+                shellcheck_version=v0.7.1
+                shellcheck_checksum=64f17152d96d7ec261ad3086ed42d18232fcb65148b44571b564d688269d36c8  
+                shellcheck_arname=shellcheck.tar.xz
+                curl --location --silent --fail --tlsv1.2 --proto '=https' \
+                    --output "$shellcheck_arname" \
+                    https://github.com/koalaman/shellcheck/releases/download/"$shellcheck_version"/shellcheck-"$shellcheck_version".linux.x86_64.tar.xz
+                sha256sum -c <(echo "$shellcheck_checksum $shellcheck_arname") > /dev/null 2>&1
+                tar -xf "$shellcheck_arname" --strip-components=1 \
+                    shellcheck-"$shellcheck_version"/shellcheck
+                rm "$shellcheck_arname"
+                chmod a+x shellcheck
+                sudo chown root:root shellcheck
+                sudo mv shellcheck "$install_dir"
+            - name: Check formatting
+              run: make format
+            - name: Check for erroneous constructs
+              run: make lint
+    pr:
+        name: Check that it builds without error
+        runs-on: ubuntu-latest
+        needs: lint
+        steps:
+            - name: Checkout the Git repository
+              uses: actions/checkout@v2
+            - name: Install missing tools
+              run: sudo apt-get install bsdtar tree
             - name: Build packages
-              run: |
-                ./scripts/repo-build package build https://toltec.delab.re/testing
-            - name: Save resulting packages as artifacts
+              run: make repo
+            - name: Save the build output
               uses: actions/upload-artifact@v2
               with:
                 name: repo

Makefile

@@ -13,6 +13,12 @@ Available targets:
     RECIPE          Build any package individually.
     RECIPE-push     Push any built package to .cache/opkg on the reMarkable.
                     (Plug in your reMarkable first!)
+    format          Check that the source code formatting follows
+                    the style guide.
+    format-fix      Automatically reformat the source code to follow
+                    the style guide.
+    lint            Perform static analysis on the source code to find
+                    erroneous constructs.
     clean           Remove all build artifacts.
 
 Where RECIPE is one of the following available recipes:
@@ -40,7 +46,29 @@ $(PUSH_PACKAGES): %:
 	ssh root@"${HOST}" mkdir -p .cache/opkg
 	scp build/packages/"$(@:%-push=%)"/*.ipk root@"${HOST}":.cache/opkg
 
+format:
+	$(info ==> Checking the formatting of shell scripts)
+	shfmt -d .
+
+format-fix:
+	$(info ==> Fixing the formatting of shell scripts)
+	shfmt -l -w .
+
+lint:
+	$(info ==> Linting shell scripts)
+	shellcheck $$(shfmt -f .)
+
 clean:
 	rm -rf build
 
-.PHONY: help repo repo-local repo-check $(PACKAGES) $(PUSH_PACKAGES) clean
+.PHONY: \
+    help \
+    repo \
+    repo-local \
+    repo-check \
+    $(PACKAGES) \
+    $(PUSH_PACKAGES) \
+    format \
+    format-fix \
+    lint \
+    clean

README.md

@@ -52,10 +52,10 @@ This repository is automatically built and published every time that a commit is
 Since all the packaged software in Toltec is free, you can also **build them from source yourself** instead of using the pre-built binaries.
 The build process is fully [reproducible](https://reproducible-builds.org/), which means that you can verify that the published packages have not been tampered with during the automated build process.
 
-[Learn how to build the repository from source →](docs/build.md)
+[Learn how to build the repository from source →](docs/building.md)
 
 ### Improve it
 
 Your contribution is welcome for adding new packages, updating existing ones or improving the build tooling.
 
-[Learn how to contribute to Toltec →](docs/contribute.md)
+[Learn how to contribute to Toltec →](docs/contributing.md)

docs/build.md renamed to docs/building.md

@@ -0,0 +1,52 @@
+## Contributing to Toltec
+
+Thank you for taking time to contribute to Toltec!
+We welcome contributions from anyone, regarding for example [reporting bugs](#reporting-a-bug), [requesting](#request-a-package) or [adding new packages](#adding-a-new-package), [upgrading existing ones](#upgrading-a-package), [improving the docs](#improving-the-documentation), or other topics.
+
+To make a request or report a bug, you simply need to [open a new issue](../../../issues/new/choose).
+
+To directly propose changes, the basic procedure is to fork this repository, make the desired changes in your newly created local copy, and open a pull request.
+When proposing changes, please make sure that you follow the [style guide](#style-guide).
+After you submit your pull request, a maintainer will take time to review your changes, request modifications and then merge your changes into the repository if they fit.
+
+### Common contributions
+
+#### Requesting a package
+
+**TODO**
+
+#### Reporting a bug
+
+**TODO**
+
+#### Adding a new package
+
+See [instructions for creating a package recipe](package.md).
+
+* clone this repository
+* switch to `testing` branch
+* edit package/$PACKAGE/package, making sure to bump the version
+* build the package (`make $PACKAGE`), making sure everything looks ok in artifacts/package/$PACKAGE/
+* install the package to your tablet, verifying things work as expected
+* for new packages, submit a pull request with the title: [$PACKAGE][$VERSION] - New Package
+* for updating packages, submit a pull request with the title: [$PACKAGE][$VERSION] - Updated Package
+
+#### Upgrading a package
+
+**TODO**
+
+#### Improving the documentation
+
+**TODO**
+
+### Style guide
+
+All contributions must follow the project’s [style guide](../.editorconfig).
+Shell scripts must also comply to [Shellcheck](https://github.com/koalaman/shellcheck).
+Sticking to a common set of conventions makes it easier for everyone to read the source code and reduces the time spent reviewing little formatting details.
+
+The code style for shell scripts will automatically be checked when you submit your pull request.
+You may also check it manually by running `make format` (or `make format-fix` to automatically fix any issues) at the root of the repository (you need to have [shfmt](https://github.com/mvdan/sh) installed on your computer for this to work).
+
+Compliance of shell scripts to Shellcheck will also automatically be checked.
+To check it manually, run `make lint` at the root of the repository (you need to have Shellcheck installed on your computer for this to work).

docs/contribute.md

@@ -3,9 +3,7 @@
 A **package recipe** is a Bash script containing metadata and instructions for building and installing a package.
 This recipe is used by the packaging script to generate installable archives for the Opkg package manager.
 
-> **Note:** A recipe is not executable and does not start with a shebang line (`#!/…`).
-> It is not meant to be executed directly, but rather sourced by the packaging script.
-> To enable syntax highlighting, the file should start with the following modeline: `# vim: set ft=sh:`.
+> **Note:** Recipes should not be marked as executable because they are not meant to be executed directly, but rather to be sourced by the packaging script.
 
 Sourcing a package recipe must have no side-effects, i.e. the metadata section can only execute commands which do not modify the system state, and stateful commands must be confined inside functions.
 

docs/contributing.md

@@ -0,0 +1,15 @@
+# vim: set ft=sh:
+# Configuration for Shellcheck in package recipes
+# See <https://github.com/koalaman/shellcheck/blob/master/shellcheck.1.md#rc-files>
+
+# Do not warn about unguarded `cd`s since recipes are always executed
+# with the -e flag set
+disable=SC2164
+
+# Do not warn about unused variables since metadata fields are expected to
+# not necessarily be used in the recipes
+disable=SC2034
+
+# Do not warn about undeclared variables since recipes may use build variables
+# such as `srcdir` or `pkgdir`
+disable=SC2154

docs/package.md

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=appmarkable
 pkgdesc="Turn your program into a very simple app for draft"
 url="https://github.com/LinusCDE/appmarkable"

package/.shellcheckrc

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=calculator
 pkgdesc="Touch-based calculator"
 url=https://github.com/reHackable/Calculator

package/appmarkable/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=draft
 pkgdesc="Launcher which wraps around the standard interface"
 url=https://github.com/dixonary/draft-reMarkable

package/calculator/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=fingerterm
 pkgdesc="Terminal emulator with an on-screen touch keyboard"
 url=https://github.com/dixonary/fingerterm-reMarkable

package/draft/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=harmony
 pkgdesc="Procedural sketching app"
 url="https://rmkit.dev/apps/harmony"
@@ -15,7 +15,7 @@ sha256sums=(157ad36bc6b345763a504b6d491a47bc3aecc828a99b1bf9fd42dab980f158a4)
 
 build() {
     pip3 install okp
-    make -j$(nproc) harmony
+    make -j"$(nproc)" harmony
 }
 
 package() {

package/fingerterm/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=koreader
 pkgdesc="An ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats"
 url=https://github.com/koreader/koreader

package/harmony/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=minesweeper
 pkgdesc="Mine detection game"
 url=https://rmkit.dev/apps/minesweeper
@@ -15,7 +15,7 @@ sha256sums=(157ad36bc6b345763a504b6d491a47bc3aecc828a99b1bf9fd42dab980f158a4)
 
 build() {
     pip3 install okp
-    make -j$(nproc) minesweeper
+    make -j"$(nproc)" minesweeper
 }
 
 package() {

package/koreader/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=nao
 pkgdesc="Nao Package Manager: opkg UI built with SAS"
 url="https://rmkit.dev/apps/nao"
@@ -16,7 +16,7 @@ sha256sums=(f8e8fce8ef7ef968fda6b4d83fe0d8160534b1bdc808e5960422075f8c8754fe)
 
 build() {
     pip3 install okp
-    make -j$(nproc) nao
+    make -j"$(nproc)" nao
 }
 
 package() {

package/mines/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=oxide
 pkgdesc="Launcher application"
 url=https://github.com/Eeems/oxide

package/nao/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=plato
 pkgdesc="Document reader"
 url=https://github.com/LinusCDE/plato
@@ -27,7 +27,7 @@ build() {
 
     # 'cargo pkgid' seems to output something different with most
     # recent nightly builds. This adjusts the filtering.
-    sed -i 's/version=.*$/version=$(cargo pkgid | cut -d "#" -f 2 | cut -d ":" -f 2)/g' download.sh
+    sed -i "s/version=.*$/version=\'$(cargo pkgid | cut -d "#" -f 2 | cut -d ":" -f 2)\'/g" download.sh
 
     # Use our toolchain
     export AR=arm-linux-gnueabihf-ar

package/oxide/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=recrossable
 pkgdesc="Solve crossword puzzles"
 url=https://github.com/sandsmark/recrossable

package/plato/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=remarkable-splash
 pkgdesc="show a splashscreen + shutdown replacement that does not clear the screen"
 url=https://github.com/ddvk/remarkable-splash

package/recrossable/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=remux
 pkgdesc="App launcher that supports multi-tasking applications"
 url="https://rmkit.dev/apps/remux"

package/remarkable-splash/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=retris
 pkgdesc="Tetris game"
 url=https://github.com/LinusCDE/retris

package/remux/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=rmservewacominput
 pkgdesc="Serve pen input on port 33333"
 url=https://github.com/LinusCDE/rmWacomToMouse

package/retris/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=simple
 pkgdesc="Simple app script for writing scripted applications"
 url="https://rmkit.dev/apps/sas"
@@ -15,7 +15,7 @@ sha256sums=(f8e8fce8ef7ef968fda6b4d83fe0d8160534b1bdc808e5960422075f8c8754fe)
 
 build() {
     pip3 install okp
-    make -j$(nproc) simple
+    make -j"$(nproc)" simple
 }
 
 package() {

package/rmservewacominput/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 pkgname=xochitl
 pkgdesc="Read documents and take notes"
 url=https://remarkable.com

package/simple/package

@@ -1,4 +1,4 @@
-# vim: set ft=sh:
+#!/usr/bin/env bash
 
 #
 # install-lib