Update metrics, semver, versions

ilyario · ilyario · commit 9634f68a4eaa · 2026-03-09T15:54:42.000+08:00
diff --git a/docs/en/index.md b/docs/en/index.md
@@ -2,6 +2,15 @@
 
 DataFlow Operator is a Kubernetes operator for streaming data between different data sources with support for message transformations.
 
+## Current Versions
+
+| Component | Version |
+|-----------|---------|
+| DataFlow Operator | <span data-version-repo="dataflow-operator/dataflow">—</span> |
+| Helm Charts | <span data-version-repo="dataflow-operator/helm-charts">—</span> |
+| DataFlow MCP | <span data-version-repo="dataflow-operator/dataflow-mcp">—</span> |
+| DataFlow Web | <span data-version-repo="dataflow-operator/dataflow-web">—</span> |
+
 ## Overview
 
 DataFlow Operator allows you to declaratively define data flows between different sources and sinks through Kubernetes Custom Resource Definitions (CRD). The operator automatically manages the lifecycle of data flows, processes messages, and applies necessary transformations.
diff --git a/docs/en/metrics.md b/docs/en/metrics.md
@@ -188,6 +188,8 @@ serviceMonitor:
 
 Import the dashboard from [grafana-dashboard.json](https://github.com/dataflow-operator/dataflow-operator/blob/main/monitoring/dashboards/grafana-dashboard.json) into Grafana to visualize metrics.
 
+**Via Helm chart (ConfigMap):** Enable `monitoring.dashboard.enabled` when installing. The dashboard is bundled in the chart (`dashboards/grafana-dashboard.json`). Grafana sidecar (kube-prometheus-stack) picks up ConfigMaps with label `grafana_dashboard: "1"`.
+
 The dashboard includes:
 - Message received/sent rate charts
 - Connector and transformer error charts
@@ -298,6 +300,8 @@ A PrometheusRule manifest with pre-configured alerts is available in the reposit
 kubectl apply -f monitoring/alerts/prometheusrule.yaml
 ```
 
+**Via Helm chart:** Enable `monitoring.prometheusRule.enabled` and set `monitoring.prometheusRule.additionalLabels` (e.g. `release: kube-prometheus-stack`) to match your Prometheus ruleSelector.
+
 **Requirements:** Prometheus Operator (e.g. kube-prometheus-stack). The `release: kube-prometheus-stack` label must match your Prometheus instance's ruleSelector. Adjust the label if you use a different Prometheus deployment.
 
 | Alert | Description |
diff --git a/docs/en/semver-release.md b/docs/en/semver-release.md
@@ -0,0 +1,64 @@
+# Automatic Versioning (Semver)
+
+The project uses automatic versioning based on [Semantic Versioning](https://semver.org/) principles using [Conventional Commits](https://www.conventionalcommits.org/).
+
+## How it works
+
+1. **On push to `main`** the `Release (Semver)` workflow is triggered
+2. **semantic-release** analyzes commits since the last tag
+3. The next version is determined by commit types:
+   - `fix:` or `fix(scope):` → **patch** (1.0.0 → 1.0.1)
+   - `feat:` or `feat(scope):` → **minor** (1.0.0 → 1.1.0)
+   - `BREAKING CHANGE:` in footer or `!` after type → **major** (1.0.0 → 2.0.0)
+4. `Chart.yaml`, `package.json` are updated, `CHANGELOG.md` is created
+5. A git tag `vX.Y.Z` and GitHub Release are created
+6. Build workflows build images with the new version
+
+## Commit format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat` — new functionality (minor)
+- `fix` — bug fix (patch)
+- `docs` — documentation (no release)
+- `style` — formatting (no release)
+- `refactor` — refactoring (no release)
+- `test` — tests (no release)
+- `chore` — maintenance changes (no release)
+
+**Examples:**
+```
+feat(api): add new endpoint for health check
+fix(processor): resolve memory leak in Kafka consumer
+docs: update installation guide
+```
+
+**Breaking change:**
+```
+feat(api)!: remove deprecated endpoint
+
+BREAKING CHANGE: /v1/legacy endpoint has been removed
+```
+
+## Configuration files
+
+- `.github/workflows/release.yml` — main release workflow
+- `.releaserc.json` — semantic-release configuration (plugins, Chart.yaml and package.json updates)
+
+## Manual release
+
+To manually create a release, create a tag:
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+Build workflows will build artifacts for this tag. For automatic Chart.yaml and package.json updates, use conventional commits and merge into main.
diff --git a/docs/javascripts/versions.js b/docs/javascripts/versions.js
@@ -0,0 +1,57 @@
+(function () {
+  const GITHUB_API = "https://api.github.com";
+  const FALLBACK = "—";
+
+  function formatVersion(tagName) {
+    if (!tagName) return FALLBACK;
+    return tagName.startsWith("v") ? tagName.slice(1) : tagName;
+  }
+
+  async function fetchLatestRelease(repo) {
+    try {
+      const res = await fetch(`${GITHUB_API}/repos/${repo}/releases/latest`, {
+        headers: { Accept: "application/vnd.github+json" },
+      });
+      if (!res.ok) return null;
+      const data = await res.json();
+      return { tagName: data.tag_name, version: formatVersion(data.tag_name) };
+    } catch {
+      return null;
+    }
+  }
+
+  function setReleaseLink(el, repo, release) {
+    el.textContent = "";
+    if (release) {
+      const a = document.createElement("a");
+      a.href = `https://github.com/${repo}/releases/tag/${release.tagName}`;
+      a.textContent = release.version;
+      a.rel = "noopener noreferrer";
+      a.target = "_blank";
+      el.appendChild(a);
+    } else {
+      el.textContent = FALLBACK;
+    }
+  }
+
+  function updateVersions() {
+    const elements = Array.from(document.querySelectorAll("[data-version-repo]"));
+    const repos = [...new Set(elements.map((el) => el.getAttribute("data-version-repo")))];
+    const cache = {};
+
+    repos.forEach((repo) => {
+      fetchLatestRelease(repo).then((release) => {
+        cache[repo] = release;
+        elements
+          .filter((el) => el.getAttribute("data-version-repo") === repo)
+          .forEach((el) => setReleaseLink(el, repo, release));
+      });
+    });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", updateVersions);
+  } else {
+    updateVersions();
+  }
+})();
diff --git a/docs/ru/index.md b/docs/ru/index.md
@@ -2,6 +2,15 @@
 
 DataFlow Operator - это Kubernetes оператор для потоковой передачи данных между различными источниками данных с поддержкой трансформаций сообщений.
 
+## Текущие версии
+
+| Компонент | Версия |
+|-----------|--------|
+| DataFlow Operator | <span data-version-repo="dataflow-operator/dataflow">—</span> |
+| Helm Charts | <span data-version-repo="dataflow-operator/helm-charts">—</span> |
+| DataFlow MCP | <span data-version-repo="dataflow-operator/dataflow-mcp">—</span> |
+| DataFlow Web | <span data-version-repo="dataflow-operator/dataflow-web">—</span> |
+
 ## Обзор
 
 DataFlow Operator позволяет декларативно определять потоки данных между различными источниками и приемниками через Kubernetes Custom Resource Definitions (CRD). Оператор автоматически управляет жизненным циклом потоков данных, обрабатывает сообщения и применяет необходимые трансформации.
diff --git a/docs/ru/metrics.md b/docs/ru/metrics.md
@@ -188,6 +188,8 @@ serviceMonitor:
 
 Импортируйте дашборд из файла [grafana-dashboard.json](https://github.com/dataflow-operator/monitoring/blob/main/dashboards/grafana-dashboard.json) в Grafana для визуализации метрик.
 
+**Через Helm chart (ConfigMap):** Включите `monitoring.dashboard.enabled` при установке. Дашборд входит в chart (`dashboards/grafana-dashboard.json`). Grafana sidecar (kube-prometheus-stack) подхватывает ConfigMap с меткой `grafana_dashboard: "1"`.
+
 Дашборд включает:
 - Графики количества полученных/отправленных сообщений
 - Графики ошибок в коннекторах и трансформерах
@@ -275,6 +277,8 @@ histogram_quantile(0.99, sum(rate(dataflow_transformer_duration_seconds_bucket[5
 kubectl apply -f monitoring/alerts/prometheusrule.yaml
 ```
 
+**Через Helm chart:** Включите `monitoring.prometheusRule.enabled` и задайте `monitoring.prometheusRule.additionalLabels` (например, `release: kube-prometheus-stack`) в соответствии с ruleSelector вашего Prometheus.
+
 **Требования:** Prometheus Operator (например, kube-prometheus-stack). Метка `release: kube-prometheus-stack` должна совпадать с ruleSelector вашего Prometheus. Измените метку, если используете другой Prometheus.
 
 | Алерт | Описание |
diff --git a/docs/ru/semver-release.md b/docs/ru/semver-release.md
@@ -0,0 +1,64 @@
+# Автоматическое версионирование (Semver)
+
+Проект использует автоматическое версионирование по принципу [Semantic Versioning](https://semver.org/) на основе [Conventional Commits](https://www.conventionalcommits.org/).
+
+## Как это работает
+
+1. **При push в `main`** запускается workflow `Release (Semver)`
+2. **semantic-release** анализирует коммиты с последнего тега
+3. По типу коммитов определяется следующая версия:
+   - `fix:` или `fix(scope):` → **patch** (1.0.0 → 1.0.1)
+   - `feat:` или `feat(scope):` → **minor** (1.0.0 → 1.1.0)
+   - `BREAKING CHANGE:` в footer или `!` после типа → **major** (1.0.0 → 2.0.0)
+4. Обновляются `Chart.yaml`, `package.json`, создаётся `CHANGELOG.md`
+5. Создаётся git-тег `vX.Y.Z` и GitHub Release
+6. Build workflows собирают образы с новой версией
+
+## Формат коммитов
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Типы:**
+- `feat` — новая функциональность (minor)
+- `fix` — исправление бага (patch)
+- `docs` — документация (без релиза)
+- `style` — форматирование (без релиза)
+- `refactor` — рефакторинг (без релиза)
+- `test` — тесты (без релиза)
+- `chore` — служебные изменения (без релиза)
+
+**Примеры:**
+```
+feat(api): add new endpoint for health check
+fix(processor): resolve memory leak in Kafka consumer
+docs: update installation guide
+```
+
+**Breaking change:**
+```
+feat(api)!: remove deprecated endpoint
+
+BREAKING CHANGE: /v1/legacy endpoint has been removed
+```
+
+## Файлы конфигурации
+
+- `.github/workflows/release.yml` — основной release workflow
+- `.releaserc.json` — конфигурация semantic-release (плагины, обновление Chart.yaml, package.json)
+
+## Ручной релиз
+
+Для ручного создания релиза создайте тег:
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+Build workflows соберут артефакты для этого тега. Для автоматического обновления Chart.yaml и package.json используйте conventional commits и merge в main.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,6 +8,9 @@ plugins:
   - search
   - mermaid2
 
+extra_javascript:
+  - javascripts/versions.js
+
 theme:
   name: material
   language: en
