Branch Naming
Feature/fix branches
Section titled “Feature/fix branches”<type>/<scope>-<short-description>Types:
| Type | Use for |
|---|---|
feat |
New feature |
fix |
Bug fix |
refactor |
Code restructuring, no behavior change |
docs |
Documentation changes |
test |
Test additions/modifications |
chore |
Build, tooling, dependency bumps |
cosmos |
Astronomer Cosmos integration work |
dbt |
dbt project additions/changes |
Scopes align with the monorepo structure: utils, vcl, db (packages), orchestration, <project_name> (e.g. mx-fuels, eia-861), <app_name>, workspace (root config), scripts.
Examples:
feat/cosmos-dbt-integrationfix/utils-keyvault-cacherefactor/orchestration-wheel-bundlingchore/workspace-uv-upgradedocs/ai-experts-personas
Deploy-triggering branches
Section titled “Deploy-triggering branches”Two long-lived branch pairs gate the CI/CD pipelines — see Architecture → CI/CD for exactly what each triggers:
| Deploy target | Dev branch | Prod branch |
|---|---|---|
Dashboard (mx_fuels_reporting_app) |
development/mx-fuels-reporting-app |
production/mx-fuels-reporting-app |
| Orchestration | orchestration-development |
orchestration-production |
The current dashboard Container Apps workflow is an exception to this table. It deploys from
main; see Architecture → CI/CD for the active workflow configuration.
Only pushes to the production/orchestration-production side normally deploy. The dashboard workflow
is the documented exception and deploys from main; treat all development branches as integration branches.
Legacy names — do not repeat
Section titled “Legacy names — do not repeat”The following branch names predate this convention and exist only in history: dev-mx_fuels_reporting-app, dev-website, prod-website, devcenter, csf, vcl. They are not a template for new branches.
Repository/branch cleanup
Section titled “Repository/branch cleanup”Stale branch criteria (per docs/ai-experts/04-workflow-release-coordinator.md): no commits in 90+ days, already merged to main, no open PRs referencing it, and not a protected branch. Deleting remote branches requires team confirmation — coordinate before running git push origin --delete <branch>.