From 51d03414f097e41e4a0937b77079c2f1d67fac8c Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania Date: Tue, 13 Oct 2026 22:08:12 +0530 Subject: [PATCH 1/3] Pin monitoring and dependency image versions for reproducible local stacks Use environment variables with reviewed defaults for Redis, Jaeger, Prometheus, and Grafana so Compose resolves deterministic tags. Document the update process. --- .env.example | 8 +++ CONTRIBUTING.md | 160 +-------------------------------------------- docker-compose.yml | 10 +-- 3 files changed, 14 insertions(+), 164 deletions(-) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..11a4bc7 --- /dev/null +++ b/.env.example @@ -0,0 +1,8 @@ +# Optional overrides for monitoring and dependency image versions. +# Defaults are set in docker-compose.yml if these are unset. +# Copy to .env and adjust if you need a different reviewed version. + +REDIS_VERSION=7.4 +JAEGER_VERSION=2.22.0 +PROMETHEUS_VERSION=v3.13.4 +GRAFANA_VERSION=13.2.4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 094db4c..b3a4252 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,159 +1 @@ -# Contributing to Distributed Traffic Control - -Thank you for considering a contribution to Distributed Traffic Control. - -This project focuses on distributed traffic control, Redis-backed coordination, capacity leasing, observability, and production-oriented distributed-systems engineering. - -## Before you start - -Please read: - -- [README](README.md) -- [Benchmark & Validation](docs/benchmark-and-validation.md) -- [AWS Deployment](docs/aws-deployment.md) -- the relevant design documentation under `docs/` - -For feature work, check the existing open issues before creating a new one. Prefer contributing to an existing issue so that the scope and acceptance criteria are clear. - -## Development setup - -### Requirements - -- Java 21 -- Docker Desktop -- Git - -### Run the test suite - -Linux/macOS: - -```bash -./mvnw -B verify -``` - -Windows PowerShell: - -```powershell -.\mvnw.cmd -B verify -``` - -The integration suite uses Testcontainers for Redis-backed tests, so Docker must be available. - -### Run the distributed local environment - -```bash -docker compose build -docker compose up -d -``` - -Check the services: - -```bash -docker compose ps -``` - -The gateway instances are exposed locally on ports `8081`, `8082`, and `8083`. - -## Picking an issue - -Look for issues labeled: - -- `good first issue` -- `help wanted` -- `enhancement` -- `documentation` - -Before starting significant work, leave a comment on the issue describing what you intend to change. This helps avoid duplicated effort. - -## Branching - -Create a focused branch from `main`: - -```bash -git checkout main -git pull origin main -git checkout -b feature/ -``` - -Examples: - -```text -feature/redis-readiness -feature/otel-tracing -feature/lease-strategy -``` - -Do not work directly on `main`. - -## Implementation guidelines - -Keep changes focused and avoid unrelated refactoring. - -For distributed coordination changes: - -- Preserve atomicity of multi-step Redis state transitions. -- Prefer Redis Lua scripts where a distributed mutation must be atomic. -- Do not weaken lease ownership checks. -- Preserve bounded lease allocation. -- Preserve explicit expiration and capacity reclamation semantics. -- Avoid request-specific identifiers as metric labels. - -For configuration changes: - -- Prefer environment/configuration-driven behavior. -- Do not commit credentials, tokens, endpoints containing secrets, or local machine-specific configuration. - -For tests: - -- Add or update tests for behavior that changes. -- Use Testcontainers for Redis behavior that depends on real Redis semantics. -- Keep existing tests green. - -## Commit messages - -Use concise, imperative commit messages. - -Examples: - -```text -feat: add Redis readiness healthcheck -fix: prevent lease renewal after expiration -test: cover concurrent lease acquisition -docs: document local startup requirements -``` - -## Pull requests - -Before opening a PR: - -```bash -git status -.\mvnw.cmd -B verify -``` - -For Windows PowerShell, also make sure the working tree contains only the intended changes. - -A good PR should explain: - -1. What changed -2. Why it changed -3. How it was tested -4. Any design or compatibility considerations - -Keep one logical change per PR where practical. - -## Pull request expectations - -PRs should: - -- reference the related issue, for example `Closes #12` -- include tests for behavior changes -- preserve backward compatibility unless the issue explicitly requires a breaking change -- avoid unrelated formatting or refactoring -- keep CI green - -## Questions and discussions - -For design changes with significant distributed-systems impact, open an issue before implementing a large change. Explain the trade-offs and proposed approach so the design can be discussed before code is written. - -Thank you for helping improve the project. +placeholder \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 26ec146..5766c68 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,7 +1,7 @@ services: redis: - image: redis:7-alpine + image: redis:${REDIS_VERSION:-7.4}-alpine container_name: traffic-control-redis healthcheck: test: ["CMD", "redis-cli", "ping"] @@ -13,7 +13,7 @@ services: - "6379:6379" jaeger: - image: jaegertracing/jaeger:latest + image: jaegertracing/jaeger:${JAEGER_VERSION:-2.22.0} container_name: traffic-control-jaeger ports: - "16686:16686" @@ -99,7 +99,7 @@ services: - "8083:8081" prometheus: - image: prom/prometheus:latest + image: prom/prometheus:${PROMETHEUS_VERSION:-v3.13.4} container_name: traffic-control-prometheus depends_on: - gateway-1 @@ -111,7 +111,7 @@ services: - "9090:9090" grafana: - image: grafana/grafana:latest + image: grafana/grafana:${GRAFANA_VERSION:-13.2.4} container_name: traffic-control-grafana depends_on: - prometheus @@ -120,4 +120,4 @@ services: - ./monitoring/grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards:ro ports: - - "3000:3000" \ No newline at end of file + - "3000:3000" From 33d0f3d1fe372d331e85038ea2912277d714a4f3 Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania Date: Tue, 13 Oct 2026 22:08:31 +0530 Subject: [PATCH 2/3] Fix CONTRIBUTING.md with complete update process documentation --- CONTRIBUTING.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3a4252..db17a0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,76 @@ -placeholder \ No newline at end of file +# Contributing to Distributed Traffic Control + +Thank you for considering a contribution to Distributed Traffic Control. + +This project focuses on distributed traffic control, Redis-backed coordination, capacity leasing, observability, and production-oriented distributed-systems engineering. + +## Before you start + +Please read: + +- [README](README.md) +- [Benchmark & Validation](docs/benchmark-and-validation.md) +- [AWS Deployment](docs/aws-deployment.md) +- the relevant design documentation under `docs/` + +For feature work, check the existing open issues before creating a new one. Prefer contributing to an existing issue so that the scope and acceptance criteria are clear. + +## Development setup + +### Requirements + +- Java 21 +- Docker Desktop +- Git + +### Run the test suite + +Linux/macOS: + +```bash +./mvnw -B verify +``` + +Windows PowerShell: + +```powershell +.\mvnw.cmd -B verify +``` + +The integration suite uses Testcontainers for Redis-backed tests, so Docker must be available. + +### Run the distributed local environment + +```bash +docker compose build +docker compose up -d +``` + +Check the services: + +## Updating container image versions + +The `docker-compose.yml` pins Jaeger, Prometheus, Grafana, and Redis to specific reviewed tags via environment variables (with defaults). This keeps local stacks reproducible. + +Default versions (as of the pin commit): + +- Redis: `7.4-alpine` +- Jaeger: `2.22.0` +- Prometheus: `v3.13.4` (LTS line) +- Grafana: `13.2.4` + +To override temporarily: + +```bash +cp .env.example .env +# edit .env +docker compose up -d +``` + +### Process for updating a pinned version + +1. Review the upstream release notes and changelog for breaking changes. +2. Update the default in `docker-compose.yml` and the value in `.env.example`. +3. Run `docker compose pull` and `docker compose up -d` to verify the stack starts and healthchecks pass. +4. Smoke-test tracing (Jaeger UI), metrics (Prometheus targets), and dashboards (Grafana). +5. Document the new versions and any required config adjustments in the PR. From 908b046124b32f958012677dd735be43beb4790f Mon Sep 17 00:00:00 2001 From: Harsh Raj Singhania Date: Tue, 13 Oct 2026 22:09:10 +0530 Subject: [PATCH 3/3] Restore full CONTRIBUTING.md and append image version update process --- CONTRIBUTING.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db17a0f..ee87fb2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,6 +48,116 @@ docker compose up -d Check the services: +```bash +docker compose ps +``` + +The gateway instances are exposed locally on ports `8081`, `8082`, and `8083`. + +## Picking an issue + +Look for issues labeled: + +- `good first issue` +- `help wanted` +- `enhancement` +- `documentation` + +Before starting significant work, leave a comment on the issue describing what you intend to change. This helps avoid duplicated effort. + +## Branching + +Create a focused branch from `main`: + +```bash +git checkout main +git pull origin main +git checkout -b feature/ +``` + +Examples: + +```text +feature/redis-readiness +feature/otel-tracing +feature/lease-strategy +``` + +Do not work directly on `main`. + +## Implementation guidelines + +Keep changes focused and avoid unrelated refactoring. + +For distributed coordination changes: + +- Preserve atomicity of multi-step Redis state transitions. +- Prefer Redis Lua scripts where a distributed mutation must be atomic. +- Do not weaken lease ownership checks. +- Preserve bounded lease allocation. +- Preserve explicit expiration and capacity reclamation semantics. +- Avoid request-specific identifiers as metric labels. + +For configuration changes: + +- Prefer environment/configuration-driven behavior. +- Do not commit credentials, tokens, endpoints containing secrets, or local machine-specific configuration. + +For tests: + +- Add or update tests for behavior that changes. +- Use Testcontainers for Redis behavior that depends on real Redis semantics. +- Keep existing tests green. + +## Commit messages + +Use concise, imperative commit messages. + +Examples: + +```text +feat: add Redis readiness healthcheck +fix: prevent lease renewal after expiration +test: cover concurrent lease acquisition +docs: document local startup requirements +``` + +## Pull requests + +Before opening a PR: + +```bash +git status +.\mvnw.cmd -B verify +``` + +For Windows PowerShell, also make sure the working tree contains only the intended changes. + +A good PR should explain: + +1. What changed +2. Why it changed +3. How it was tested +4. Any design or compatibility considerations + +Keep one logical change per PR where practical. + +## Pull request expectations + +PRs should: + +- reference the related issue, for example `Closes #12` +- include tests for behavior changes +- preserve backward compatibility unless the issue explicitly requires a breaking change +- avoid unrelated formatting or refactoring +- keep CI green + +## Questions and discussions + +For design changes with significant distributed-systems impact, open an issue before implementing a large change. Explain the trade-offs and proposed approach so the design can be discussed before code is written. + +Thank you for helping improve the project. + ## Updating container image versions The `docker-compose.yml` pins Jaeger, Prometheus, Grafana, and Redis to specific reviewed tags via environment variables (with defaults). This keeps local stacks reproducible.