Branching And Pull Requests

Why this matters

As a Data Visualization Engineer, you frequently adjust dashboards, SQL models, and chart configs. Branching lets you safely develop changes without breaking production. Pull Requests (PRs) invite review, catch issues early, and document the intent behind changes. Real tasks you will handle:

• Adding a new metric and chart to a KPI dashboard.
• Fixing a broken color scale or axis on a production report.
• Refactoring a SQL model used by multiple visuals and confirming nothing regresses.

With clear branches and PRs, you ship improvements faster and with fewer surprises.

Concept explained simply

• Branch: a named line of work. Use it to develop a feature or fix.
• Main (or master): your stable, deployable branch.
• Pull Request: a request to merge your branch into main after review and checks.
• Review: peers validate logic, performance, and visualization quality.

Practical defaults for

• Branch types: feature/ for new work, fix/ for non-critical fixes, hotfix/ for urgent production issues.
• Naming: feature/sales-conversion-rate (short, descriptive, kebab-case).
• Commits: small, meaningful messages, e.g., feat: add conversion_rate metric to sales model.
• PR size: under ~300 lines if possible; split large changes.
• Checks: run linters/tests locally (e.g., SQL checks, dbt build, unit tests for transforms) before opening/merging PR.

Worked examples

Example 1 — Add a new KPI to a dashboard

1. Create a feature branch:

   git checkout -b feature/sales-conversion-rate

2. Modify files: SQL model for conversion rate and dashboard config.
3. Commit in small steps:

   git add models/sales_conversion.sql
   git commit -m "feat: add sales conversion rate model"
   
   git add dashboards/sales.json
   git commit -m "feat: add conversion rate chart to sales dashboard"

4. Update from main and rebase if needed:

   git fetch origin
   git rebase origin/main

5. Push and open PR:

   git push -u origin feature/sales-conversion-rate

   PR description includes problem, approach, validation steps, and screenshots.

6. Address review comments, then merge when checks pass.

Example 2 — Urgent hotfix for a wrong color scale

1. Branch from main:

   git checkout main
   git pull
   git checkout -b hotfix/fix-color-scale-dashboard

2. Change the color mapping in the dashboard JSON/config.
3. Commit and push:

   git add dashboards/sales.json
   git commit -m "fix: correct color scale for revenue bands"
   git push -u origin hotfix/fix-color-scale-dashboard

4. Open a small PR, request quick review, merge once checks pass.

Example 3 — Resolve a merge conflict in a chart spec

1. You have a PR open for feature/add-legend. Main changed the same file.
2. Update and rebase:

   git fetch origin
   git rebase origin/main

3. Git shows conflicts in dashboards/sales.json. Edit to keep both the new legend and the recent main changes.
4. Continue rebase and test locally:

   git add dashboards/sales.json
   git rebase --continue
   # run validations: dbt build, preview dashboard locally

5. Push the rebased branch:

   git push --force-with-lease

6. PR updates automatically; request final review and merge.

Hands-on exercises

Practice locally in any Git repository (a sample analytics repo or a new one with placeholder files).

Exercise 1 — Feature branch + PR

Goal: add a new metric and open a PR.

1. Create a new branch named feature/sales-conversion-rate.
2. Add or edit a SQL/model file that computes conversion_rate.
3. Commit with a clear message and push the branch.
4. Open a PR with a description: context, change summary, validation steps, and impact.

• Branch created
• Commit message uses conventional style (feat/fix)
• PR description includes validation steps
• CI/tests run clean locally before PR

Exercise 2 — Resolve a merge conflict

Goal: practice rebasing and resolving conflicts.

1. On a branch, change a line in a dashboard config (e.g., title or color).
2. On main, change the same line differently and commit.
3. Rebase your branch onto main, resolve the conflict, and continue the rebase.
4. Push with --force-with-lease and update the PR.

• Conflict resolved correctly
• Local tests/preview confirm no regressions
• PR notes the conflict resolution for reviewers

Common mistakes and self-check

• Huge PRs that are hard to review. Fix: split into smaller, coherent PRs.
• Vague commit/PR messages. Fix: write the why, what, validation, impact.
• Skipping local checks. Fix: run linters/tests and preview dashboards.
• Branching from an outdated main. Fix: git fetch and rebase/merge before starting.
• Force-pushing without --force-with-lease. Fix: always use --force-with-lease.

Practical projects

• Personal KPI Board: build a tiny repo with one SQL model and one dashboard JSON; iterate via branches and PRs.
• Visualization Refresh: refactor chart themes across multiple files in small PRs; prove no visual regressions with screenshots.
• Data Model Tightening: add a metric to a dbt-like model and update a chart; document tests and roll-back plan in the PR.

Who this is for

• Data Visualization Engineers collaborating on dashboards and BI assets
• Analytics Engineers and BI Developers contributing to shared repos
• Anyone moving from solo work to team-based analytics development

Prerequisites

• Basic Git: clone, add, commit, push, pull
• Familiarity with your BI/analytics stack (SQL, dashboard configs)
• Local environment to preview changes (optional but helpful)

Learning path

1. Branch basics: create, switch, update from main
2. PR essentials: small PRs, good descriptions, request review
3. Conflict resolution: rebase/merge, fix conflicts safely
4. Team conventions: naming, commit style, reviewers, CI checks
5. Advanced: draft PRs, cherry-pick, revert strategies

Next steps

• Adopt a branch naming convention for your team
• Create a PR template with context, validation, and impact
• Automate checks (linters/tests) to run on each PR

Mini challenge

Make two parallel changes to the same chart file on different branches, then practice resolving the conflict and documenting the resolution in the PR. Keep each PR under 200 lines and include before/after screenshots.

Ready to test your knowledge?

Take the quick test below. Everyone can take it for free; only logged-in users will have their progress saved.