Skip to content

chore(docs): v2.0.0 doc consolidation, fix stale examples + ship MIGRATION + multi-source sample#38

Merged
fxthiry merged 1 commit intorelease/2.0.0from
chore/v2-doc-consolidation
Apr 16, 2026
Merged

chore(docs): v2.0.0 doc consolidation, fix stale examples + ship MIGRATION + multi-source sample#38
fxthiry merged 1 commit intorelease/2.0.0from
chore/v2-doc-consolidation

Conversation

@fxthiry
Copy link
Copy Markdown
Owner

@fxthiry fxthiry commented Apr 16, 2026

Closes the documentation gaps that were not addressed during the multi-source feature work, before tagging v2.0.0 final.

What ships

  • Three stale v1.x example configs (README.md Quick Start, docs/getting-started.md minimal, examples/cisco-switches/config.yaml) migrated to the v2.0.0 map shape with a default: source. They would otherwise have been rejected by --validate after a copy-paste.
  • MIGRATION.md at repo root: 5-section guide for v1.x upgraders covering the pre-upgrade checklist, config before/after, Prometheus metric migration with PromQL examples, notifier output format changes (Mattermost footer + default webhook payload), and a rollback path. Linked from README.md and CHANGELOG.md.
  • examples/multi-source/: complete reference config (2 sources, 3 rules covering pinned single-source + fan-out) plus a README.md explaining the routing matrix. Closes the explicit ask from the issue #34 reporter.
  • README Features list reworked: multi-source bullet is now position Welcome to Valerter ! #1 with an outcome-led wording ("One Valerter for every VictoriaLogs you run"). Blockquote callout right after Quick Start points v1.x upgraders at MIGRATION.md.
  • docs/performance.md accuracy banner: throughput numbers in that page were measured against v1.x (single task per rule); the v2.0.0 N×M task model and max_streams cap are now mentioned at the top with a note that re-measurement is pending.
  • Two new integration tests lock the shipped samples against future drift:
    • shipped_config_example_validates runs --validate on config/config.example.yaml.
    • shipped_examples_pass_validate iterates examples/*/config.yaml and runs --validate on each.

Validation

  • cargo test — 551 tests pass (479 lib + 72 integration, +2 new in integration_validate)
  • cargo clippy --all-targets --all-features -- -D warnings — clean
  • cargo fmt --check — clean
  • All three shipped example files: valerter --validate -c <path> → exit 0
  • Manual: README Quick Start YAML extracted to a temp file, --validate → exit 0
  • Manual link check: every internal markdown link added (README → MIGRATION, README → examples/multi-source, MIGRATION → CHANGELOG sections) resolves on disk

Out of scope (deferred to follow-up)

  • Tagline reword (e.g. "One alerting control plane for all your VictoriaLogs")
  • ASCII / SVG diagram for multi-source routing
  • "Concepts" page bridging README and configuration.md
  • GHSA filing for the email body_html security advisory
  • Snippet harvester test that validates inline ```yaml blocks in .md files
  • Runtime error message that points users at MIGRATION.md when the legacy victorialogs.url shape is detected (code change, separate concern)

…ATION + multi-source sample

Three v1.x example configs (README Quick Start, docs/getting-started.md
minimal, examples/cisco-switches/config.yaml) were rejected by --validate
on v2.0.0; they are now migrated to the map shape with a `default:` source.

Adds a top-level MIGRATION.md with a 5-section guide for v1.x upgraders:
pre-upgrade checklist, config migration with before/after snippets,
Prometheus metric migration with PromQL examples, notifier output format
changes (Mattermost footer + default webhook payload), and a rollback
path. Linked from README and CHANGELOG.

Adds examples/multi-source/ with a complete reference config and a
README explaining the routing matrix (one rule pinned to prod, one
pinned to staging, one fan-out across both). Closes the explicit ask
from the issue #34 reporter for a sample multi-source config.

README Features list hoists "One Valerter for every VictoriaLogs you
run" to position #1, reworded outcome-led. A blockquote callout right
after Quick Start points v1.x upgraders at MIGRATION.md.

docs/performance.md gains an accuracy banner since the throughput
numbers were measured against v1.x (single task per rule); the
multi-source N x M task model and max_streams cap are mentioned and
will be re-measured separately.

Two new integration tests in tests/integration_validate.rs lock the
shipped samples against future drift: shipped_config_example_validates
and shipped_examples_pass_validate (iterates examples/*/config.yaml).
The 2.0.0 entry in CHANGELOG gains one Added line pointing at the new
sample and MIGRATION.md.
@fxthiry fxthiry merged commit 3c5e0f5 into release/2.0.0 Apr 16, 2026
@fxthiry fxthiry mentioned this pull request Apr 16, 2026
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant