Naming Conventions For Changes

Why this matters

Clear, consistent names make your BI work traceable and safe. As a BI Analyst you will:

• Scan commit history to find when a KPI changed.
• Debug a broken report and trace the exact change that introduced the issue.
• Collaborate with engineers and analysts across branches and pull requests.
• Pass audits by showing what changed, where, and why.
• Hand off work smoothly with searchable, predictable history.

Concept explained simply

Naming conventions are agreed patterns for branches, commits, pull requests (PRs), and migration files. They encode three things:

• What changed (summary).
• Where it changed (scope: model, report, metric, etc.).
• Why it changed (ticket or reason).

type(scope): short-summary (TICKET-ID)

Optional body: key context, breaking change notes, validation notes

type/TICKET-ID-kebab-case-summary
ex: feat/ABC-123-add-customer-ltv-metric

type(scope): summary (TICKET-ID)

YYYY-MM-DD_ticket-summary.sql
ex: 2025-01-15_ABC-123_add_customer_ltv_metric.sql

Mental model

Think of your names as an address on a map:

• Street = type (feat, fix, refactor)
• Neighborhood = scope (report, model, metric)
• House number = ticket (ABC-123)
• Door sign = summary (kebab-case, concise)

If each piece is present, anyone can navigate history quickly.

Core conventions you can adopt today

• Use types consistently: feat for new KPI/model; fix for bug; refactor for internal rework.
• Use a clear scope: report, dashboard, metric, model, sql, pipeline, docs.
• Attach the ticket ID: keep traceability to planning and approvals.
• Write a short summary: imperative mood, lowercase, kebab-case for names.
• Date-stamp migration files with ISO format for natural sorting.

Worked examples

Example 1 — Fix a broken date filter in a dashboard

Branch:

fix/ABC-612-fix-null-date-filter-sales-overview

Commit:

fix(report): correct null date filter on Sales Overview (ABC-612)

Cause: WHERE clause excluded NULL but slicer allowed it.
Validation: compared 7-day totals before/after; matches warehouse source.

PR title:

fix(report): correct null date filter on Sales Overview (ABC-612)

Example 2 — Add a new customer LTV metric

Branch:

feat/ABC-457-add-customer-ltv-metric

Commit:

feat(metrics): add customer_ltv metric to sales_mart (ABC-457)

Notes: 365-day window; excludes refunded orders.
Validation: unit test for edge cases; compared to finance sample.

Migration file:

2025-01-15_ABC-457_add_customer_ltv_metric.sql

Example 3 — Refactor a model for performance

Branch:

refactor/OPS-044-slim-sales-mart-joins

Commit:

refactor(model): simplify joins in sales_mart, no logic change (OPS-044)

Notes: replaced lateral join with window function; runtime -35%.

PR title:

refactor(model): simplify joins in sales_mart, no logic change (OPS-044)

Practice exercises

These match the exercises in the Exercises panel below. Do them here first, then check your answers.

Exercise 1: Name the branch, commit, PR, and migration

Scenario: Ticket ABC-457. You add a new customer LTV metric to the sales_mart model and a SQL migration creates a helper view. Produce:

1. Branch name.
2. Commit message (subject line + brief body).
3. PR title.
4. Migration file name.

• [ ] Uses type(scope) format.
• [ ] Includes ABC-457.
• [ ] Summary is short, imperative, and kebab-case where applicable.
• [ ] Migration uses ISO date and clear summary.

Exercise 2: Rewrite messy commit messages

Scenario: Standardize these commits for tickets ABC-612, ABC-598, OPS-044, ABC-701, and ABC-702:

1. "changed stuff in report" (ABC-612)
2. "new column" (ABC-598)
3. "speed up" (OPS-044)
4. "bug fix for metric" (ABC-701)
5. "updated docs" (ABC-702)

Rewrite each using type(scope): summary (TICKET-ID). Add 1 brief validation note if relevant.

• [ ] Correct type chosen.
• [ ] Scope is specific.
• [ ] Includes ticket ID.
• [ ] Clear, imperative summary.

Common mistakes and how to self-check

• Missing ticket ID. Self-check: Does every branch/commit/PR include ABC-###?
• Vague summaries like "update" or "changes". Self-check: Can a teammate guess what changed without opening files?
• Inconsistent types. Self-check: Would a reader expect user-visible output? If yes, feat; if not, refactor/perf; if a bug, fix.
• Overloaded scope like "data". Self-check: Use concrete scopes: model, report, metric, sql, pipeline, docs.
• No time-ordered migrations. Self-check: Do filenames start with ISO date?

Who this is for

• BI Analysts working with SQL models, dashboards, and metrics.
• Analytics Engineers collaborating via Git.
• Data-savvy PMs contributing to BI repositories.

Prerequisites

• Basic Git workflow: clone, branch, commit, push, PR.
• Familiarity with your BI stack (SQL models, dashboards, metrics).

Learning path

1. Git basics: staging, commits, diffs.
2. Naming conventions for changes (this lesson).
3. Branching strategies and code review practices.
4. Safe releases and rollback playbooks.

Practical projects

• Create a one-page "BI Naming Conventions" doc for your team with examples for commits, branches, PRs, and migrations.
• Standardize an existing repo: rename branches in progress and squash/reword the last 10 commit messages for clarity.
• Add validation notes to commits for two sensitive metrics (how you verified correctness).

Next steps

• Use the cheat sheet for your next PR.
• Introduce a pre-PR checklist: type, scope, ticket, summary, validation note.
• Share the conventions in your team channel for feedback and adoption.

Mini challenge

Timebox 20 minutes. Take a recent messy change and rework it:

1. Create a clean branch name.
2. Reword the last commit to standard.
3. Draft a PR title and 2-sentence body with validation.

feat(report): add regional margin % to Executive Overview (ABC-735)

Validation: matched 3 regions to Finance calc; differences < 0.1pp.

Ready to test yourself?

Take the Quick Test below to check mastery. The test is available to everyone; only logged-in users get saved progress.