From f54325720e4166b4d4e7683a646267ae8b78feea Mon Sep 17 00:00:00 2001
From: Choko <choko@curioswitch.org>
Date: Thu, 9 May 2024 12:06:06 +0900
Subject: [PATCH] Add CI workflow and some more docs

---
 .github/workflows/ci.yaml | 31 +++++++++++++++++++++++++++++++
 RATIONALE.md              | 27 +++++++++++++++++++++++++++
 README.md                 |  4 ++++
 go-build.code-workspace   |  4 ++++
 4 files changed, 66 insertions(+)
 create mode 100644 .github/workflows/ci.yaml
 create mode 100644 RATIONALE.md

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
new file mode 100644
index 0000000..eeec9b2
--- /dev/null
+++ b/.github/workflows/ci.yaml
@@ -0,0 +1,31 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "*"
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - macos-13
+          - macos-14
+          - ubuntu-22.04
+          - windows-2022
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.work
+          cache-dependency-path: "**/go.sum"
+
+      - name: run checks
+        run: go run build check
diff --git a/RATIONALE.md b/RATIONALE.md
new file mode 100644
index 0000000..4f2ef1f
--- /dev/null
+++ b/RATIONALE.md
@@ -0,0 +1,27 @@
+# Notable rationale of go-build
+
+## Use goyek
+
+We do not use Makefile, probably the most common tool for builds in Go, because
+it is tedious to do complex tasks and hard to make cross-platform.
+
+We have used [Mage](https://magefile.org/) in other projects and it works well -
+for projects that currently use Makefile, it can be easier to convince members
+to migrate to it vs goyek. It has some quirks though.
+
+For further details, see goyek's [explanation](https://github.com/goyek/goyek?tab=readme-ov-file#alternatives)
+which is fair and follows our thoughts.
+
+## Use gofumpt
+
+We prefer to have less bikeshedding in code reviews, and this includes formatting.
+While this isn't as prevalent in the Go ecosystem yet, it is common practice in others
+such as NodeJS. Where possible, we will prefer auto-formatting that enforces as much
+structure as possible. It's automatic, so why not?
+
+## Use gci
+
+We believe there is significant stylistic benefit in having consistent import
+ordering and grouping, something the Go standard goimports [cannot do](https://github.com/golang/go/issues/20818).
+Both gci and gosimports are great tools for this, and we choose gci because it
+is also integrated with golangci-lint, making it simpler to verify in CI.
diff --git a/README.md b/README.md
index 4286c4c..df94046 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,10 @@ a Go workspace to keep build-specific libraries like goyek out of your standard
 modules file, or remove the go.mod / go.sum files to include it as a normal
 package.
 
+Using the folder `build` is a goyek convention, but any folder name will work,
+i.e. if you already use `build` for transient artifacts. Note that these tasks
+use `out` for transient artifacts.
+
 A list of all tasks can be seen with `go run ./build -h`. The commonly used tasks
 will likely be:
 
diff --git a/go-build.code-workspace b/go-build.code-workspace
index c9076de..b8a7d54 100644
--- a/go-build.code-workspace
+++ b/go-build.code-workspace
@@ -11,6 +11,10 @@
   "settings": {
     "editor.tabSize": 2,
     "eslint.workingDirectories": [{ "mode": "auto" }],
+    "[github-actions-workflow]": {
+      "editor.formatOnSave": true,
+      "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
     "gopls": {
       "formatting.gofumpt": true
     },