From e3e52dfe69f5240fb6ca0ebcdfea27141f55e53c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Menu?= <mickael.menu@gmail.com>
Date: Sun, 7 Jan 2024 20:26:02 +0100
Subject: [PATCH] Add `CONTRIBUTING.md` (#378)

---
 CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..703e824
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,61 @@
+# Contributing to `zk`
+
+## Understanding the codebase
+
+### Building the project
+
+It is recommended to use the `Makefile` for compiling the project, as the `go` command requires a few parameters.
+
+```shell
+make build
+```
+
+This will be expanded to the following command:
+
+```shell
+CGO_ENABLED=1 GOARCH=arm64 go build -tags "fts5" -ldflags "-X=main.Version=`git describe --tags --match v[0-9]* 2> /dev/null` -X=main.Build=`git rev-parse --short HEAD`"
+```
+
+* `CGO_ENABLED=1` enables CGO, which is required by the `mattn/go-sqlite3` dependency.
+* `GOARCH=arm64` is only required for Apple Silicon chips.
+* `-tags "fts5"` enables the FTS option with `mattn/go-sqlite3`, which handles much of the magic behind `zk`'s `--match` filtering option.
+* ``-ldflags "-X=main.Version=`git describe --tags --match v[0-9]* 2> /dev/null` -X=main.Build=`git rev-parse --short HEAD`"`` will automatically set `zk`'s build and version numbers using the latest Git tag and commit SHA.
+
+### Automated tests
+
+The project is vetted with two different kind of automated tests: unit tests and end-to-end tests.
+
+#### Unit tests
+
+Unit tests are using the standard [Go testing library](https://pkg.go.dev/testing). To execute them, use the command `make test`.
+
+They are ideal for testing parsing output or individual API edge cases and minutiae.
+
+#### End-to-end tests
+
+Most of `zk`'s functionality is tested with functional tests ran with [`tesh`](https://github.com/mickael-menu/tesh), which you can execute with `make tesh` (or `make teshb`, to debug whitespaces changes).
+
+When addressing a GitHub issue, it's a good idea to begin by creating a `tesh` file in `tests/issue-XXX.tesh`. If a starting notebook state is required, it can be added under `tests/fixtures`.
+
+If you modify the output of `zk`, you may disrupt some `tesh` files. You can use `make tesh-update` to automatically update them with the correct output.
+
+### CI workflows
+
+Several GitHub action workflows are executed when pull requests are merged or releases are created.
+
+* `.github/workflows/build.yml` checks that the project can be built and the tests still pass.
+* `.github/workflows/codeql.yml` runs static analysis to vet code quality.
+* `.github/workflows/release.yml` submits a new version to Homebrew when a Git version tag is created.
+* `.github/workflows/triage.yml` automatically tags old issues and PRs as staled.
+
+## Releasing a new version
+
+When `zk` is ready to be released, you can update the `CHANGELOG.md` ([for example](https://github.com/zk-org/zk/commit/ea4457ad671aa85a6b15747460c6f2c9ad61bf73)) and create a new Git version tag (for example `v0.13.0`). Make sure you follow the [Semantic Versioning](https://semver.org) scheme.
+
+Then, create [a new GitHub release](https://github.com/zk-org/zk/releases) with a copy of the latest `CHANGELOG.md` entries and the binaries for all supported platforms.
+
+Binaries can be created automatically using `make dist-linux` and `make dist-macos`.
+
+Unfortunately, `make dist-macos` must be run manually on both an Apple Silicon and Intel chips. The Linux builds are created using Docker and [these custom images](https://github.com/zk-org/zk-xcompile).
+
+This process is convoluted because `zk` requires CGO with `mattn/go-sqlite3`, which prevents using Go's native cross-compilation. Transitioning to a CGO-free SQLite driver such as [cznic/sqlite](https://gitlab.com/cznic/sqlite) could simplify the distribution process significantly.
\ No newline at end of file