-
Notifications
You must be signed in to change notification settings - Fork 3
Developer Conventions
Single main branch. All work happens on feature branches and merges to main via pull request.
Clean up commits before requesting review — atomic, meaningful commits on main are the goal.
# Rewrite dev branch history before PR review
git rebase -i main # or: git reset --soft main
git push --force-with-leaseSquash or rebase (not merge commit) when merging a PR.
Note
See these tips to split up a commit on a dev branch.
- Open a draft PR early — helps reviewers track in-progress work and gives the author a checklist.
- PRs must have a description: title, links to relevant issues, and a summary of changes.
- For significant or non-obvious code, annotate directly on the diff; for higher-level discussion, use an issue or Teams rather than cluttering the PR.
- Mark Ready for Review and assign reviewer(s) when development is complete.
- Re-request review after significant changes post-feedback.
We use black for Python and sqlfluff for SQL.
black --diff --color --check directory/file.py
black directory/file.py
sqlfluff lint products/.../file.sql
sqlfluff fix products/.../file.sqlFor code comments, use consistent tags (inspired by Better Comments):
# TODO refactor this function to make it faster
# ! Deprecated function, do not use
# * This is an important note
# ? Should this variable be renamed for consistency?See dbt's own style guide for reference. We use dbt-checkpoint to validate conventions via pre-commit:
# Environment variables required by the product's profiles.yml must be set
dbt deps --profiles-dir products/product_directory --project-dir products/product_directory
dbt seed --profiles-dir products/product_directory --project-dir products/product_directory
pre-commit run --all-filesWe use three layers (dbt's "marts" renamed to "product"):
| Layer | Prefix | Purpose |
|---|---|---|
staging/ |
stg__ |
Single-source transforms only — column renames, type casts, CRS changes. No joins. |
intermediate/ |
int__ |
Core transformation logic — joins, business rules, complex calculations. |
product/ |
(none) | Output tables ready for export. Columns renamed for business users. |
Group related intermediate models into subfolders (e.g. intermediate/buffers/, intermediate/zoning/) when there are multiple files with a shared domain. Use the subfolder name in the prefix: int_buffers__.
If a single-source transform is simple enough for staging but logically belongs alongside complex intermediate models in the same subdomain, putting it in the intermediate subfolder is acceptable.