Release v0.2.0: single-source the version, wildcard it in docs

Introduces a VERSION variable in the top-level Makefile as the
authoritative source for the module's reported version. A new
version-header target writes src/version.h only when the content
would change, so no-op rebuilds don't rewrite the file. The C source
#includes that header in place of a hardcoded #define; the
user-guide's install example is wildcarded
(libnginx-mod-http-ipng-stats_*_amd64.deb) so it doesn't drift.

The design doc still references v0.2.0 by name — operators read it as
a point-in-time description, not a moving target.

debian/changelog keeps its own 0.2.0-1 entry because dpkg reads the
package version from there directly; the e2e test is updated to match
the JSON schema bump to 2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -3,6 +3,7 @@ build/
 objs/
 *.so
 *.o
+src/version.h
 
 # Debian build outputs (dpkg-buildpackage writes these to the parent dir,
 # but if a helper extracts them here, ignore them)

Makefile

@@ -18,9 +18,16 @@ MODULE_NAME := ngx_http_ipng_stats_module
 MODULE_DIR  := $(CURDIR)
 BUILD_DIR   := $(CURDIR)/build
 
+# Single source of truth for the module version. When cutting a release,
+# bump this AND add a matching top entry to debian/changelog — dpkg reads
+# the package version from there directly. The C code picks up VERSION
+# via the generated src/version.h (written by the version-header target
+# below and depended on by the module build).
+VERSION     := 0.2.0
+
 NGINX_SRC ?=
 
-.PHONY: help build pkg-deb robot-test install-deps clean fetch-nginx-src
+.PHONY: help build pkg-deb robot-test install-deps clean fetch-nginx-src version-header
 
 TEST ?= tests/
 
@@ -50,7 +57,19 @@ build: $(BUILD_DIR)/$(MODULE_NAME).so
 	@echo "  echo 'load_module modules/$(MODULE_NAME).so;' | sudo tee /etc/nginx/modules-enabled/50-mod-http-ipng-stats.conf"
 	@echo "  sudo nginx -t && sudo nginx -s reload"
 
-$(BUILD_DIR)/$(MODULE_NAME).so: fetch-nginx-src
+# version-header: write src/version.h iff its contents would change. The
+# target is .PHONY so it's re-evaluated every build, but the file itself
+# is only touched on VERSION bumps — keeps the .so from rebuilding when
+# nothing has actually changed.
+version-header:
+	@NEW='#define NGX_HTTP_IPNG_STATS_VERSION "$(VERSION)"'; \
+	if [ ! -f $(MODULE_DIR)/src/version.h ] \
+	   || [ "$$NEW" != "$$(cat $(MODULE_DIR)/src/version.h)" ]; then \
+		echo "Generating src/version.h (VERSION=$(VERSION))"; \
+		echo "$$NEW" > $(MODULE_DIR)/src/version.h; \
+	fi
+
+$(BUILD_DIR)/$(MODULE_NAME).so: version-header fetch-nginx-src
 	@set -e; \
 	if [ -z "$(NGINX_SRC)" ]; then \
 		NGX_SRC="$(BUILD_DIR)/nginx-src"; \
@@ -154,4 +173,5 @@ install-deps:
 
 clean:
 	rm -rf $(BUILD_DIR) tests/.venv tests/out
+	rm -f $(MODULE_DIR)/src/version.h
 	-dh_clean 2>/dev/null || true

debian/changelog

@@ -1,3 +1,23 @@
+nginx-ipng-stats-plugin (0.2.0-1) unstable; urgency=medium
+
+  * Reduce scrape cardinality.
+    - Status codes are collapsed to six class lanes
+      (1xx/2xx/3xx/4xx/5xx/unknown) on the counter key. Per-(source, vip)
+      counter cardinality is now bounded at six regardless of response mix.
+    - Histograms drop the code label entirely and aggregate across classes
+      per (source, vip).
+    - New nginx_ipng_latency_total counter (with code class label) exposes
+      per-class mean latency via latency_total / requests_total.
+    - New nginx_ipng_bytes_in and nginx_ipng_bytes_out histograms; bucket
+      bounds configurable via the new ipng_stats_byte_buckets directive.
+    - JSON schema bumped to 2. Records are now per-(source, vip) with an
+      inner `classes` map.
+    - Operators needing per-three-digit-code breakdowns should consume
+      ipng_stats_logtail off-host; the stats zone intentionally trades
+      that resolution for a smaller, bounded scrape.
+
+ -- Pim van Pelt <pim@ipng.ch>  Fri, 17 Apr 2026 12:36:57 +0000
+
 nginx-ipng-stats-plugin (0.1.0-1) unstable; urgency=medium
 
   * Initial release.

docs/design.md

@@ -5,7 +5,7 @@
 
 | | |
 | --- | --- |
-| **Status** | Draft — describes intended behavior for `v0.1.0` |
+| **Status** | Draft — describes intended behavior for `v0.2.0` |
 | **Author** | Pim van Pelt `<pim@ipng.ch>` |
 | **Last updated** | 2026-04-16 |
 | **Audience** | Operators and contributors deploying per-device, per-VIP traffic observability on nginx |

docs/user-guide.md

@@ -23,7 +23,7 @@ On Debian Trixie (and newer), the module is distributed as `libnginx-mod-http-ip
 package and loads cleanly into it without recompiling nginx itself.
 
 ```
-sudo apt install ./libnginx-mod-http-ipng-stats_0.1.0-1_amd64.deb
+sudo apt install ./libnginx-mod-http-ipng-stats_*_amd64.deb
 ```
 
 The package will:

src/ngx_http_ipng_stats_module.c

@@ -66,7 +66,9 @@ typedef struct {
 extern ngx_module_t  ngx_http_log_module;
 
 
-#define NGX_HTTP_IPNG_STATS_VERSION          "0.1.0"
+/* NGX_HTTP_IPNG_STATS_VERSION is generated at build time from the
+ * top-level Makefile's VERSION variable — see `make version-header`. */
+#include "version.h"
 #define NGX_HTTP_IPNG_STATS_SCHEMA_VERSION   2
 
 /* Default histogram buckets in milliseconds (FR-2.3). */

tests/01-module/01-e2e.robot

@@ -40,7 +40,7 @@ JSON scrape
     ${rc}    ${output} =    Run And Return Rc And Output
     ...    curl -sf -H 'Accept: application/json' ${SCRAPE_URL} | python3 -m json.tool
     Should Be Equal As Integers    ${rc}    0
-    Should Contain    ${output}    "schema": 1
+    Should Contain    ${output}    "schema": 2
 
 # --- Per-device attribution ---