From 97445137a8b5246feeb5cebce6c3feb4cb6f8ea4 Mon Sep 17 00:00:00 2001 From: Alexander Olzem Date: Fri, 24 Apr 2026 09:12:22 +0200 Subject: [PATCH 1/4] docs: add design decisions --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6f7dae0..7e92188 100644 --- a/README.md +++ b/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 From 1c0190c505783f9b1e318565897e31281ad8b7a0 Mon Sep 17 00:00:00 2001 From: Alexander Olzem Date: Fri, 24 Apr 2026 09:12:48 +0200 Subject: [PATCH 2/4] fix: provide a fallback for OS and ARCH if go is not installed --- common.mk | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/common.mk b/common.mk index e0e017c..c306894 100644 --- a/common.mk +++ b/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 From 131b9da325f845eb11f48621e96b322d2a9fc456 Mon Sep 17 00:00:00 2001 From: Alexander Olzem Date: Fri, 24 Apr 2026 09:16:21 +0200 Subject: [PATCH 3/4] feat: add github actions --- .github/release-drafter.yml | 58 +++++++++++++++++++++ .github/workflows/issues-add-labels.yaml | 18 +++++++ .github/workflows/issues-add-to-project.yml | 19 +++++++ .github/workflows/release-drafter.yaml | 44 ++++++++++++++++ 4 files changed, 139 insertions(+) create mode 100644 .github/release-drafter.yml create mode 100644 .github/workflows/issues-add-labels.yaml create mode 100644 .github/workflows/issues-add-to-project.yml create mode 100644 .github/workflows/release-drafter.yaml diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml new file mode 100644 index 0000000..1d00390 --- /dev/null +++ b/.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 diff --git a/.github/workflows/issues-add-labels.yaml b/.github/workflows/issues-add-labels.yaml new file mode 100644 index 0000000..7821609 --- /dev/null +++ b/.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 diff --git a/.github/workflows/issues-add-to-project.yml b/.github/workflows/issues-add-to-project.yml new file mode 100644 index 0000000..494eb52 --- /dev/null +++ b/.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 }} diff --git a/.github/workflows/release-drafter.yaml b/.github/workflows/release-drafter.yaml new file mode 100644 index 0000000..bdf5126 --- /dev/null +++ b/.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 }} From 0a41afe17ce30a6b09d3c22f0f596fe6a2c2e30c Mon Sep 17 00:00:00 2001 From: Alexander Olzem Date: Fri, 24 Apr 2026 09:20:16 +0200 Subject: [PATCH 4/4] chore: bump release --- example/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/example/Makefile b/example/Makefile index 4279f37..4ab60a5 100644 --- a/example/Makefile +++ b/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 && \