docs: add design decisions

.github/release-drafter.yml

@@ -0,0 +1,58 @@
+name-template: "$RESOLVED_VERSION"
+tag-template: "$RESOLVED_VERSION"
+categories:
+  - title: "Features"
+    labels:
+      - "feat"
+      - "feature"
+      - "enhancement"
+  - title: "Bug Fixes"
+    labels:
+      - "fix"
+      - "bugfix"
+      - "bug"
+  - title: "Maintenance"
+    labels:
+      - "docs"
+      - "doc"
+      - "chore"
+change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
+change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
+version-template: "v$MAJOR.$MINOR.$PATCH"
+version-resolver:
+  major:
+    labels:
+      - "major"
+  minor:
+    labels:
+      - "minor"
+  patch:
+    labels:
+      - "patch"
+  default: patch
+exclude-labels:
+  - "skip-changelog"
+autolabeler:
+  - label: "chore"
+    files:
+      - "*.md"
+    branch:
+      - '/docs{0,1}\/.+/'
+  - label: "bug"
+    branch:
+      - '/fix\/.+/'
+      - '/bug\/.+/'
+      - '/bugfix\/.+/'
+    title:
+      - "/fix/i"
+      - "/bug/i"
+      - "/bugfix/i"
+  - label: "feature"
+    branch:
+      - '/feat\/.+/'
+      - '/feature\/.+/'
+      - '/enhancement\/.+/'
+template: |
+  ## Changes
+
+  $CHANGES

.github/workflows/issues-add-labels.yaml

@@ -0,0 +1,18 @@
+name: Label issues
+on:
+  issues:
+    types:
+      - reopened
+      - opened
+jobs:
+  label_issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - run: gh issue edit "$NUMBER" --add-label "$LABELS"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}
+          LABELS: needs-triage

.github/workflows/issues-add-to-project.yml

@@ -0,0 +1,19 @@
+name: Add issues to project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add issue to project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v1.0.2
+        with:
+          project-url: https://github.com/orgs/opendefensecloud/projects/3
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}

.github/workflows/release-drafter.yaml

@@ -0,0 +1,44 @@
+name: Release Drafter
+
+on:
+  push:
+    # branches to consider in the event; optional, defaults to all
+    branches:
+      - main
+
+  # pull_request event is required only for autolabeler
+  pull_request:
+    # Only following types are handled by the action, but one can default to all as well
+    types: [opened, reopened, synchronize]
+  # pull_request_target event is required for autolabeler to support PRs from forks
+  # pull_request_target:
+  #   types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  update_release_draft:
+    permissions:
+      # write permission is required to create a github release
+      contents: write
+      # write permission is required for autolabeler
+      # otherwise, read permission is required at least
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      # (Optional) GitHub Enterprise requires GHE_HOST variable set
+      #- name: Set GHE_HOST
+      #  run: |
+      #    echo "GHE_HOST=${GITHUB_SERVER_URL##https:\/\/}" >> $GITHUB_ENV
+
+      # Drafts your next Release notes as Pull Requests are merged into "master"
+      - uses: release-drafter/release-drafter@v7
+        # (Optional) specify config name to use, relative to .github/. Default: release-drafter.yml
+        # with:
+        #   config-name: my-config.yml
+        #   disable-autolabeler: true
+        with:
+          commitish: main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,10 +1,7 @@
 # dev-kit
 
-Development tools for [opendefense.cloud](https://github.com/opendefensecloud) projects.
-
-## What is this?
-
 A library that provides a pre-configured development environment.
+
 Copy the files from `example/` into your project and adjust them for your needs.
 
 ## Features
@@ -19,11 +16,30 @@ Copy the files from `example/` into your project and adjust them for your needs.
 ### Make targets
 
 The included `common.mk` provides:
-- `make fmt` - format code
-- `make lint` - run linters
-- `make test` - run tests
-- `make build` - build the project
-- `make generate` - run code generation
+
+| Target                | Description                                 |
+| ---                   | ---                                         |
+| `help`                | Display all available targets               |
+| `clean`               | Remove the `bin/` directory                 |
+| `mod`                 | Run `go mod tidy`, `download`, and `verify` |
+| `golangci-lint`       | Run golangci-lint                           |
+| `shellcheck`          | Run shellcheck on shell scripts             |
+| `scan`                | Scan for vulnerabilities using osv-scanner  |
+| `setup-local-cluster` | Create a Kind cluster for local development |
+
+### Variables
+
+| Variable             | Default                     | Description                       |
+| ---                  | ---                         | ---                               |
+| `BUILD_PATH`         | `$(shell pwd)`              | Base directory for local binaries |
+| `LOCALBIN`           | `$(BUILD_PATH)/bin`         | Directory for installed binaries  |
+| `OSV_SCANNER_CONFIG` | `./.osv-scanner.toml`       | Path to osv-scanner configuration |
+| `OS`                 | `$(shell $(GO) env GOOS)`   | Current Operating System          |
+| `ARCH`               | `$(shell $(GO) env GOARCH)` | Current CPU architecture          |
+
+Any binary defined in your `tools.lock` is also available as a Make target
+(e.g. `make $(CONTROLLER_GEN)`). Take a look at the variables defined in
+common.mk for a list of pre-defined binary paths.
 
 To include `common.mk` into your own `Makefile` use this snippet or copy the provided `Makefile` in `example/`:
 
@@ -107,6 +123,43 @@ Modify `flake.nix` to adjust Go version, packages, and pre-commit hooks:
 }
 ```
 
+## Design Decisions
+
+### Why Nix?
+
+Nix provides reproducible, declarative development environments. It ensures
+that every developer (and CI) operates in an identical environment, eliminating
+"works on my machine" issues. Nix also enables us to share modules and overlays
+across projects, reducing duplication and maintaining consistency.
+
+### Why Make over alternatives?
+
+We evaluated several build tools:
+
+- **magefile**: While Go-native, it is not ideal for scripting workflows that
+  primarily orchestrate external binaries.
+
+- **just**: Offers a modern syntax but lacks a built-in module sharing system.
+  Migrating our Make ecosystem to just would swap one tool for another without
+  meaningful architectural gains.
+
+Make remains pragmatic: it is universally available and familiar to most
+developers. While it has its quirks — tabs for indentation, the occasional `$`
+escape — it provides all the features we need. The `curl common.mk` pattern
+effectively gives us a module system without introducing a new dependency.
+
+### Why not devenv?
+
+We used [devenv](https://devenv.sh) for some time but moved away due to its
+dependency on an additional binary and the complexity it introduced during
+upgrades.
+
+### Why not Go's tool directive?
+
+Go 1.24's `tool` directive in `go.mod` pulls tooling into the local Go module
+ecosystem. This often leads to dependency conflicts, as tools compiled together
+with the project can clash with the project's own dependencies.
+
 ## Documentation
 
 - [Nix](https://nixos.org) - Package manager and dev environment

common.mk

@@ -27,8 +27,10 @@ KUBECTL ?= kubectl
 SHELLCHECK ?= shellcheck
 YQ ?= yq
 
-OS := $(shell $(GO) env GOOS)
-ARCH := $(shell $(GO) env GOARCH)
+OS := $(or $(shell $(GO) env GOOS 2>/dev/null), \
+	$(shell uname -s | tr '[:upper:]' '[:lower:]'))
+ARCH := $(or $(shell $(GO) env GOARCH 2>/dev/null), \
+	$(shell uname -m | sed -E 's/x86_64/amd64/;s/i386|i686/386/;s/aarch64|arm64/arm64/;s/armv7l/arm/'))
 
 # Binaries provided by go install / tools.lock
 ADDLICENSE ?= $(LOCALGOBIN)/addlicense

example/Makefile

@@ -1,5 +1,5 @@
 # Include ODC common make targets
-DEV_KIT_VERSION := v1.0.0
+DEV_KIT_VERSION := v1.0.1
 -include common.mk
 common.mk:
 	curl --fail -sSL https://raw.githubusercontent.com/opendefensecloud/dev-kit/$(DEV_KIT_VERSION)/common.mk -o common.mk.download && \