Branching And Pull Requests Basics

Why this matters

As a BI Analyst, you change SQL queries, dbt models, notebooks, and dashboard definition files. Branching lets you work safely without breaking main. Pull requests (PRs) let teammates review, test, and approve changes before they go live.

• Collaborate on complex KPI definitions without overwriting each other.
• Propose report updates, get feedback, and track what changed and why.
• Fix urgent production bugs quickly and cleanly.
• Keep a clear history so audits and rollbacks are easy.

Concept explained simply

A branch is a separate line of work. The main branch is the stable source of truth. You create a feature branch to make changes. A pull request is a formal proposal to merge your branch back into main after review.

Mental model

Imagine main as the highway. A branch is a safe exit where you can tinker with your car. When it’s ready, the PR is the checkpoint that verifies your car is safe before you rejoin the highway.

Core workflow

1. Update local main: git checkout main then git pull.
2. Create a branch: git checkout -b feat/new-kpi.
3. Make changes; commit early and often.
4. Push the branch: git push -u origin feat/new-kpi.
5. Open a PR, add context, request review.
6. Address feedback, resolve conflicts, then merge when approved.
7. Delete the branch after merge to keep things tidy.

Worked examples

Example 1: Add a new KPI definition

1. Start from the latest main:

   git checkout main
   git pull

2. Create a branch:

   git checkout -b feat/new-kpi-dau

3. Edit models/kpis/daily_active_users.sql.
4. Commit and push:

   git add models/kpis/daily_active_users.sql
   git commit -m "feat: add DAU KPI using 7d activity window"
   git push -u origin feat/new-kpi-dau

5. Open a PR, describe why the KPI matters, how to validate, and any data quality checks.

Example 2: Hotfix a broken dashboard filter

1. Update main and branch for a fix:

   git checkout main
   git pull
   git checkout -b fix/dashboard-filter-bug

2. Edit the affected file (e.g., dashboards/sales.json) to correct the filter.
3. Commit and push:

   git add dashboards/sales.json
   git commit -m "fix: correct region filter to include EMEA"
   git push -u origin fix/dashboard-filter-bug

4. Open a PR with clear reproduction steps and the fix verification steps.

Example 3: Team collaboration on a dbt model change

1. Create a branch:

   git checkout -b feat/refactor-orders-model

2. Commit work in small steps:

   git commit -m "refactor: split orders into base + dims"
   # after tests
   git commit -m "test: add freshness checks for orders_base"

3. Push and open a PR. Use a checklist in the description (tests passing, docs updated, owners notified).
4. Respond to review comments with follow-up commits until approved.

Branch naming patterns and commit messages

• Branches: feat/... for new work, fix/... for bugs, chore/... for maintenance. Examples: feat/new-kpi-dau, fix/null-customer-id.
• Commits: Use a short, imperative summary and optional body. Example:

  feat: add DAU KPI
  
  - counts active users with 7-day window
  - used by exec dashboard

Merge conflicts: simple resolution

Conflicts happen when two branches change the same lines. Git marks conflicts like this:

<<<<<<< HEAD
-- your version --
=======
-- incoming version --
>>>>>>> origin/main

1. Edit the file to keep the correct lines and remove the markers.
2. Stage and continue:

   git add path/to/file.sql
   git commit -m "chore: resolve merge conflict in file.sql"

Exercises you can do now

These match the exercises at the bottom of the page. Do them in a sample repo or a new test repository you create locally.

Exercise 1: Feature branch and PR

• Create branch feat/add-revenue-kpi from updated main.
• Add or modify a SQL file to compute a revenue KPI.
• Commit and push; open a PR with a clear description and validation steps.

Exercise 2: Resolve a merge conflict

• On your branch, edit the same lines in a file that you also edit on main (simulate a conflict).
• Merge main into your branch and resolve the conflict.
• Commit the resolution and push updates to the PR.

Common mistakes and self-check

• Working directly on main. Fix: always branch from updated main.
• Large PRs with mixed changes. Fix: split into small, focused PRs.
• Vague commit messages. Fix: describe intent and scope.
• Forgetting to pull before branching. Fix: git checkout main && git pull first.
• Ignoring failed checks/tests. Fix: make tests pass before merge.

Practical projects

• Analytics KPI Pack: Add 3 new KPIs in separate branches and open 3 PRs. Merge them sequentially after reviews.
• Dashboard Refactor: Split a large query into modular parts in a feature branch. Include a PR checklist for docs and tests.
• Hotfix Drill: Simulate a production bug, fix it with a small fix/ branch, and document validation steps in the PR.

Who this is for

• BI Analysts and Analytics Engineers new to Git collaboration.
• Analysts who currently share SQL via files or chats and want safer teamwork.

Prerequisites

• Basic Git commands: init, add, commit, status.
• Basic terminal/CLI usage.
• A sample repository with at least one SQL or model file.

Learning path

1. Initialize and commit locally.
2. Learn branching and PR basics (this lesson).
3. Practice conflict resolution and code review etiquette.
4. Adopt PR checklists and small, frequent merges.

Next steps

• Automate simple checks (lint SQL, run tests) in your PRs.
• Create a team PR template with business impact, test steps, and owners.
• Set naming conventions for branches and labels.

Mini challenge

Pick one of your existing reports. In a new feat/ branch, improve a KPI definition or add a filter. Open a PR with:

• A clear one-sentence summary of the change.
• Three bullet points on how to validate it.
• Potential downstream impacts.

Optional: Ask a teammate to review and leave one improvement suggestion.