Add GoReleaser configuration for GitHub Releases and update CI workflow

.github/workflows/release.yml

@@ -9,24 +9,36 @@ permissions:
   contents: write
 
 jobs:
-  goreleaser:
+  release:
+    name: Goreleaser publish
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          fetch-depth: 0 # needed for changelog and tags
 
-      - name: Set up Go
+      - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: stable
+          go-version: '1.23.x'
+          cache: true
+
+      - name: Tidy check
+        run: |
+          go mod tidy
+          git diff --exit-code -- go.mod go.sum
+
+      - name: Build
+        run: go build ./...
+
+      - name: Test (race)
+        run: go test -race ./...
 
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v6
         with:
-          distribution: goreleaser
           version: latest
-          args: release --clean
+          args: release --clean --config .goreleaser.yaml
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.goreleaser.yaml

@@ -0,0 +1,45 @@
+# GoReleaser config for Poindexter (library)
+# This configuration focuses on generating GitHub Releases with changelog notes.
+# Since Poindexter is a library (no CLI binaries), we skip building archives.
+
+project_name: poindexter
+
+dist: dist
+
+before:
+  hooks:
+    - go mod tidy
+
+builds: [] # no binaries to build for this library
+
+dockers: []
+
+archives: [] # do not produce tarballs/zip since there are no binaries
+
+checksum:
+  name_template: "checksums.txt"
+
+changelog:
+  use: github
+  sort: asc
+  filters:
+    exclude:
+      - '^docs:'
+      - '^chore:'
+      - '^test:'
+      - '^ci:'
+      - 'README'
+
+release:
+  prerelease: false
+  draft: false
+  mode: replace
+  footer: |
+    --
+    Generated by GoReleaser. See CHANGELOG.md for curated notes.
+
+report_sizes: true
+
+# Snapshot configuration for non-tag builds (optional local use)
+snapshot:
+  name_template: "{{ incpatch .Version }}-next+{{ .ShortCommit }}"

.goreleaser.yml

@@ -1,71 +1,49 @@
-# This is an example .goreleaser.yml file with some sensible defaults.
-# Make sure to check the documentation at https://goreleaser.com
+# NOTE: This file is intentionally a mirror of .goreleaser.yaml.
+# Canonical configuration lives in .goreleaser.yaml; keep both in sync.
+# CI release workflow explicitly uses .goreleaser.yaml to avoid ambiguity.
 
-# The lines below are called `modelines`. See `:help modeline`
-# Feel free to remove those if you don't want/need to use them.
-# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
-# vim: set ts=2 sw=2 tw=0 fo=cnqoj
+# GoReleaser config for Poindexter (library)
+# This configuration focuses on generating GitHub Releases with changelog notes.
+# Since Poindexter is a library (no CLI binaries), we skip building archives.
 
-version: 2
+project_name: poindexter
+
+dist: dist
 
 before:
   hooks:
-    # You may remove this if you don't use go modules.
     - go mod tidy
-    # you may remove this if you don't need go generate
-    - go generate ./...
 
-builds:
-  - env:
-      - CGO_ENABLED=0
-    goos:
-      - linux
-      - windows
-      - darwin
-    goarch:
-      - amd64
-      - arm64
-    # Optional: Exclude specific combinations
-    ignore:
-      - goos: windows
-        goarch: arm64
+builds: [] # no binaries to build for this library
 
-archives:
-  - format: tar.gz
-    # this name template makes the OS and Arch compatible with the results of `uname`.
-    name_template: >-
-      {{ .ProjectName }}_
-      {{- title .Os }}_
-      {{- if eq .Arch "amd64" }}x86_64
-      {{- else if eq .Arch "386" }}i386
-      {{- else }}{{ .Arch }}{{ end }}
-      {{- if .Arm }}v{{ .Arm }}{{ end }}
-    # use zip for windows archives
-    format_overrides:
-      - goos: windows
-        format: zip
+dockers: []
+
+archives: [] # do not produce tarballs/zip since there are no binaries
+
+checksum:
+  name_template: "checksums.txt"
 
 changelog:
+  use: github
   sort: asc
   filters:
     exclude:
-      - "^docs:"
-      - "^test:"
-      - "^ci:"
-      - "^chore:"
-      - "^build:"
-      - Merge pull request
-      - Merge branch
-
-checksum:
-  name_template: 'checksums.txt'
-
-snapshot:
-  version_template: "{{ incpatch .Version }}-next"
+      - '^docs:'
+      - '^chore:'
+      - '^test:'
+      - '^ci:'
+      - 'README'
 
 release:
-  github:
-    owner: Snider
-    name: Poindexter
+  prerelease: false
   draft: false
-  prerelease: auto
+  mode: replace
+  footer: |
+    --
+    Generated by GoReleaser. See CHANGELOG.md for curated notes.
+
+report_sizes: true
+
+# Snapshot configuration for non-tag builds (optional local use)
+snapshot:
+  name_template: "{{ incpatch .Version }}-next+{{ .ShortCommit }}"

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 - pkg.go.dev Examples: `ExampleNewKDTreeFromDim_Insert`, `ExampleKDTree_TiesBehavior`, `ExampleKDTree_Radius_none`.
 - Lint: enable `errcheck` in `.golangci.yml` with test-file exclusion to reduce noise.
 - CI: enable module cache in `actions/setup-go` to speed up workflows.
+- Docs: README cross-link to Performance page and add a concise “Choosing a metric” tip section.
 
 ## [0.3.0] - 2025-11-03
 ### Added
@@ -25,6 +26,9 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 ### Added
 - Normalization stats helpers: `AxisStats`, `NormStats`, `ComputeNormStats2D/3D/4D`.
 - Builders that reuse stats: `Build2DWithStats`, `Build3DWithStats`, `Build4DWithStats`.
+- CI: coverage integration (`-coverprofile`), Codecov upload and badge.
+- CI: benchmark runs publish artifacts per Go version.
+- Docs: Performance page (`docs/perf.md`) and MkDocs nav entry.
 - pkg.go.dev examples: `ExampleBuild2DWithStats`, `ExampleBuild4DWithStats`.
 - Tests for stats parity, min==max safety, and dynamic update with reused stats.
 - Docs: API reference section “KDTree Normalization Stats (reuse across updates)”; updated multi-dimensional docs with WithStats snippet.
@@ -46,6 +50,7 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 - KDTree public API with generic payloads and helper builders (Build2D/3D/4D).
 - Docs pages for DHT examples and multi-dimensional KDTree usage.
 
-[Unreleased]: https://github.com/Snider/Poindexter/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/Snider/Poindexter/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Snider/Poindexter/releases/tag/v0.3.0
 [0.2.1]: https://github.com/Snider/Poindexter/releases/tag/v0.2.1
 [0.2.0]: https://github.com/Snider/Poindexter/releases/tag/v0.2.0

CONTRIBUTING.md

@@ -51,9 +51,29 @@ Also run `go vet ./...` periodically.
 
 ## Release process
 
-Maintainers:
-- Update CHANGELOG.md.
-- Tag releases `vX.Y.Z`.
-- Consider updating docs and README badges if needed.
+We use GoReleaser to publish GitHub Releases when a semver tag is pushed.
+
+Steps for maintainers:
+- Ensure `CHANGELOG.md` has an entry for the version and links are updated at the bottom (Unreleased compares from latest tag).
+- Ensure `poindexter.Version()` returns the new version and tests pass.
+- Merge all changes to `main` and wait for CI to be green.
+- Create an annotated tag and push:
+  
+  ```bash
+  VERSION=vX.Y.Z
+  git tag -a "$VERSION" -m "Release $VERSION"
+  git push origin "$VERSION"
+  ```
+- GitHub Actions workflow `.github/workflows/release.yml` will run tests and GoReleaser to publish the Release.
+- Verify the release notes and badges (README release badge updates automatically).
+
+Optional:
+- Dry-run locally without publishing:
+  
+  ```bash
+  goreleaser release --skip=publish --clean
+  ```
+
+See `RELEASE.md` for more details.
 
 Thanks for helping improve Poindexter!

README.md

@@ -5,6 +5,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/Snider/Poindexter)](https://goreportcard.com/report/github.com/Snider/Poindexter)
 [![Vulncheck](https://img.shields.io/badge/govulncheck-enabled-brightgreen.svg)](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck)
 [![codecov](https://codecov.io/gh/Snider/Poindexter/branch/main/graph/badge.svg)](https://codecov.io/gh/Snider/Poindexter)
+[![Release](https://img.shields.io/github/v/release/Snider/Poindexter?display_name=tag)](https://github.com/Snider/Poindexter/releases)
 
 A Go library package providing utility functions including sorting algorithms with custom comparators.
 
@@ -76,6 +77,15 @@ Explore runnable examples in the repository:
 - Insert is O(1) amortized; delete by ID is O(1) via swap-delete; order is not preserved.
 - Concurrency: the KDTree type is not safe for concurrent mutation. Protect with a mutex or share immutable snapshots for read-mostly workloads.
 - See multi-dimensional examples (ping/hops/geo/score) in docs and `examples/`.
+- Performance guide: see docs/Performance for benchmark guidance and tips: [docs/perf.md](docs/perf.md) • Hosted: https://snider.github.io/Poindexter/perf/
+
+#### Choosing a metric (quick tips)
+- Euclidean (L2): smooth trade-offs across axes; solid default for blended preferences.
+- Manhattan (L1): emphasizes per-axis absolute differences; good when each unit of ping/hop matters equally.
+- Chebyshev (L∞): dominated by the worst axis; useful for strict thresholds (e.g., reject high hop count regardless of ping).
+- Cosine: angle-based for vector similarity; pair it with normalized/weighted features when direction matters more than magnitude.
+
+See the multi-dimensional KDTree docs for end-to-end examples and weighting/normalization helpers: [Multi-Dimensional KDTree (DHT)](docs/kdtree-multidimensional.md).
 
 ## License