From 7fed1f63a6d1c4f1c53d35ac424303bfbc5e44c8 Mon Sep 17 00:00:00 2001 From: Christopher Allen Lane 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 `. +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/