Skip to content

Correct sdp-expectation-notifications docs: drop coverage, alert naming, destination semantics - #19

Merged
vmariiechko merged 1 commit into
mainfrom
docs/sdp-expectation-notifications-corrections
Jul 26, 2026
Merged

Correct sdp-expectation-notifications docs: drop coverage, alert naming, destination semantics#19
vmariiechko merged 1 commit into
mainfrom
docs/sdp-expectation-notifications-corrections

Conversation

@vmariiechko

Copy link
Copy Markdown
Owner

Related Issue

Closes #

Summary

Documentation-only pass on the sdp-expectation-notifications asset: seven corrections grounded in two live verification sessions (2026-07-26 drop/destination testing, 2026-07-17/18 hygiene build). No pipeline code, YAML defaults, or test behavior changed. Also includes two small ROADMAP.md cleanups and finalizes v1.12.1.

Changes

  • Drop coverage documented. The hook filters purely on failed_records > 0 and never inspects the expectation's action type, so warn and drop rules notify identically; the README previously framed the pattern as WARN-only. Adds the lived 2026-07-26 numbers (drop expectation matching the WARN row's shape, dropped_records field, additive backstop sum).
  • Naming corrected. "Alert v2"/"Alerts v2" renamed to "Databricks SQL alert(s)" across the README, in-bundle doc, skill files, alert YAML comments, and install prompt text, matching current Databricks docs. alerts-v2 kept only where it names an actual CLI command.
  • Notification destinations clarified. Destinations serve only Databricks SQL and jobs, not the event hook, and a destination is a wrapper around a webhook (its own admin setup, Slack/Teams-specific), not a substitute for one. Documents the measured non-deduplication when a destination and user_email share an address.
  • No-webhook guidance added. Readers and the companion skill are now steered to deploy the backstop alone when there is no Slack/Teams/webhook target.
  • Backstop cron tied to pipeline mode. Flags that a continuous pipeline needs a tighter cron/window than the shipped daily default, at the cost of more warehouse wake-ups.
  • Grace-period claim softened. Replaces the overclaimed "roughly 20 seconds" with an honest, unestablished bound and the actionable rule (single-digit-second hook work).
  • Skill CLI gotcha documented. databricks notification-destinations create's misleading warning/empty echo, so an agent scripting it doesn't mistake success for failure.
  • ROADMAP.md cleanup (unrelated to the asset, bundled here): fills in the placeholder "Pre-commit Hooks" idea with a proper scoped proposal, and adds a new "Shared Bundles Support" idea.

Change Area

  • Core template (template/, schema, helpers)
  • Asset Library (assets/<name>/)
  • Both
  • Docs / tests / infrastructure only

Configuration Axes Affected

  • Environment setup (full/minimal, dev environment)
  • Compute type (classic/serverless/both)
  • Permissions / RBAC
  • CI/CD pipelines (Azure DevOps, GitHub Actions, GitLab)
  • Cloud provider (Azure/AWS/GCP)
  • Unity Catalog / schemas
  • Template schema (databricks_template_schema.json)
  • Template helpers (library/helpers.tmpl)
  • Asset Library (new asset, asset schema, or framework changes)
  • None of the above (docs, tests, infrastructure only)

Testing

  • All tests pass (pytest tests/ -V) — 2446 passed, 163 skipped, unchanged from the pre-edit baseline
  • Manual template generation tested
  • New tests added for new functionality (docs-only change; no new tests needed, confirmed no existing test asserts the prose being changed)

Release (if this PR cuts a release)

  • CHANGELOG.md finalized: [Unreleased] renamed to [1.12.1] - 2026-07-26, fresh empty [Unreleased] added above
  • Both version markers bumped to 1.12.1 (pyproject.toml and template/{{.project_name}}/bundle_init_config.json.tmpl)
  • Version guard test passes (tests/test_release_metadata.py)

Checklist

  • Go template syntax is valid (no unclosed {{ }} blocks)
  • No .tmpl files appear in generated output
  • Generated YAML files are valid
  • Documentation updated (if behavior changed) — N/A, no behavior changed

…ng, destination semantics

Seven documentation corrections grounded in two live verification sessions
(2026-07-26 drop/destination testing, 2026-07-17/18 hygiene build): the hook
covers drop expectations identically to warn, not just warn; "Alert v2"
renamed to "Databricks SQL alert" to match current Databricks naming;
notification destinations clarified as a webhook wrapper, not a hook
delivery path or a Slack-without-a-webhook shortcut; readers with no
webhook target are now steered to deploy the backstop alone; the backstop
cron is tied to pipeline mode; the platform's teardown grace period is
stated as an unestablished bound instead of a false "roughly 20 seconds";
and the skill documents a CLI gotcha in notification-destinations create.
No pipeline code, YAML defaults, or test behavior changed.

Also cleans up two ROADMAP.md Future Ideas entries: fills in the
placeholder Pre-commit Hooks item with a proper scoped proposal, and adds a
new Shared Bundles Support idea for consuming an external shared-bundle
path via sync.paths/include.

Bumps to v1.12.1 (patch) per RELEASING.md.
@vmariiechko
vmariiechko merged commit fa8e904 into main Jul 26, 2026
1 check passed
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