From f52bc7d7b8781134951c1498f7bf5962e6d4ee72 Mon Sep 17 00:00:00 2001
From: Bauke <me@bauke.xyz>
Date: Fri, 23 Jun 2023 13:03:49 +0200
Subject: [PATCH] Copy the Development document from Tildes Shepherd.

---
 DEVELOPMENT.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..66d37fb
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,100 @@
+# Development Guide
+
+## Prerequisites
+
+### Nix + Direnv
+
+If you have [Nix](https://nixos.org/) with flakes enabled and [Direnv](https://direnv.net/) installed, all you need to do is `direnv allow` the directory and all the prerequisites will be automatically installed. This may take a moment on first load.
+
+Firefox and git are excluded, which are assumed to already be present on your system.
+
+### Manual
+
+To build and develop Tildes ReExtended you will need:
+
+* [git](https://git-scm.com)
+* [NodeJS](https://nodejs.org) (recommended 18.16.0)
+* [pnpm](https://pnpm.io) (recommended 8.6.0)
+* [cargo-make](https://sagiegurari.github.io/cargo-make/)
+
+## cargo-make
+
+All the different tasks we'd want to do are setup in `Makefile.toml` to be used with `cargo-make` (or the `makers` alias).
+
+In the Tasks section below you can find a list of all the tasks, or you can look at the Makefile itself, where all the tasks have a description of what they do.
+
+### Environment
+
+Two important environment variables are `BROWSER` and `NODE_ENV`.
+
+`BROWSER` dictates what browser should be targeted, by default `BROWSER="firefox"`. To target Chromium set `BROWSER="chromium"`.
+
+`NODE_ENV` dictates minifying and optimization found in `source/build.ts`, by default `NODE_ENV="development"` which does no minifying and includes sourcemaps in the build. Setting `NODE_ENV="production"` will minify and exclude sourcemaps.
+
+### Tasks
+
+<details>
+<summary>Click to view all tasks</summary>
+
+* The most common scenario will likely be that you want a live-reloading browser instance, this can be done using the `dev` task.
+
+```sh
+# If makers doesn't work, replace it with cargo-make.
+makers dev
+
+# To change the environment, prefix the command with the
+# variables you want to set.
+BROWSER="chromium" NODE_ENV="production" makers dev
+```
+
+* To watch for changes but without starting a live-reloading browser instance, use the `watch` task.
+
+```sh
+makers watch
+
+# Which is a simple alias for the following.
+WATCH="true" makers build
+```
+
+* To start a browser instance with an already built extension present in the `build/` directory, the `run` task is available. Note that this will fail if the extension hasn't been built before.
+
+```sh
+makers run
+```
+
+* To clean the build directory, a `clean` task is available. This uses `trash-cli` so if you accidentally remove something and want it back, check your trash bin where you can restore it.
+
+```sh
+makers clean
+
+# Clean the Chromium directory.
+BROWSER="chromium" makers clean
+```
+
+* To lint the code, `lint` is the task.
+
+```sh
+makers lint
+
+# To only lint JS or SCSS.
+makers lint-js
+makers lint-scss
+```
+
+* To pack the WebExtension for publishing, `pack` is what you need.
+
+```sh
+# Make sure to set NODE_ENV, otherwise the extension size will be
+# a lot bigger than it needs to be.
+NODE_ENV="production" makers pack
+
+# To pack Chromium.
+BROWSER="chromium" NODE_ENV="production" makers pack
+```
+
+* Mozilla Addons requires the zipped source code too, since we're using minification, so `zip-source` is available. This uses Git's `archive` command.
+
+```sh
+makers zip-source
+```
+</details>