From 7fed1f63a6d1c4f1c53d35ac424303bfbc5e44c8 Mon Sep 17 00:00:00 2001
From: Christopher Allen Lane <chris@chris-allen-lane.com>
Date: Tue, 5 Jul 2022 15:05:42 -0400
Subject: [PATCH] docs: create `HACKING.md`

Create a `HACKING.md` file for onboarding new developers to `cheat`.
---
 CONTRIBUTING.md |  4 +++-
 HACKING.md      | 57 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 HACKING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9b9a778..45b186d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,8 @@ tracker][issues] to discuss with the maintainer whether it would be considered
 for merging.
 
 `cheat` is mostly mature and feature-complete, but may still have some room for
-new features.
+new features. See [HACKING.md][hacking] for a quick-start guide to `cheat`
+development.
 
 #### Add documentation ####
 Did you encounter features, bugs, edge-cases, use-cases, or environment
@@ -41,6 +42,7 @@ Please open all pull-requests against the `develop` branch.
 
 [cheat]: https://github.com/cheat/cheat
 [cheatsheets]: https://github.com/cheat/cheatsheets
+[hacking]: HACKING.md
 [issues]: https://github.com/cheat/cheat/issues 
 [pr]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork
 [wiki]: https://github.com/cheat/cheat/wiki
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..b518998
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,57 @@
+Hacking
+=======
+The following is a quickstart guide for developing `cheat`.
+
+## 1. Install system dependencies
+Before you begin, you must install a handful of system dependencies. The
+following are required, and must be available on your `PATH`:
+
+- `git`
+- `go` (>= 1.17 is recommended)
+- `make`
+
+The following dependencies are optional:
+- `docker`
+- `pandoc` (necessary to generate a `man` page)
+
+## 2. Install utility applications
+Run `make setup` to install `scc` and `revive`, which are used by various
+`make` targets.
+
+## 3. Development workflow
+After your environment has been configured, your development workflow will
+resemble the following:
+
+1. Make changes to the `cheat` source code.
+2. Run `make test` to run unit-tests.
+3. Fix compiler errors and failing tests as necessary.
+4. Run `make`. A `cheat` executable will be written to the `dist` directory.
+5. Use the new executable by running `dist/cheat <command>`.
+6. Run `make install` to install `cheat` to your `PATH`.
+7. Run `make build-release` to build cross-platform binaries in `dist`.
+8. Run `make clean` to clean the `dist` directory when desired.
+
+You may run `make help` to see a list of available `make` commands.
+
+### Developing with docker
+It may be useful to test your changes within a pristine environment. An
+Alpine-based docker container has been provided for that purpose.
+
+If you would like to build the docker container, run:
+```sh
+make docker-setup
+```
+
+To shell into the container, run:
+```sh
+make docker-sh
+```
+
+The `cheat` source code will be mounted at `/app` within the container.
+
+If you would like to destroy this container, you may run:
+```sh
+make distclean
+```
+
+[go]: https://go.dev/