Branching & Commits

TL;DR: Solis’s real branch naming and commit conventions, and the Shopify-GitHub theme sync feature that’s a separate, optional thing.

Branch naming convention

Branch off an up-to-date main for every change, and name the branch type/short-description/echologyx-id:

git checkout main
git pull
git checkout -b feature/announcement-bar/144

Branch type	Use for	Example
`feature`	A new section, block, snippet, or capability	`feature/announcement-bar/144`
`component`	Building or reworking a single reusable UI component	`component/slider/150`
`bug-fix`	Fixing broken behavior on an existing component	`bug-fix/product-card/130`
`config`	Theme settings, tooling, CI, or repo configuration	`config/fix-workflow/143`
`docs`	Documentation only	`docs/update-readme/151`
`refactor`	Restructuring code with no change in behavior	`refactor/cart-drawer/158`

The trailing number is the Echologyx ID, so the branch always traces back to its author, not a GitHub username.

Branch types and commit types are separate vocabularies — they don’t have to match. A bug-fix/product-card/130 branch will carry fix: commits, and a component/slider/150 branch will usually carry feat: commits. Name the branch for the work, name each commit for what that specific commit does.

Keep each branch scoped to a single change — it’s easier to review cleanly.

✅ Do	❌ Don’t
`feature/announcement-bar/144`	`jsmith-announcement-bar` (no type, no Echologyx ID)
One focused change per branch	`feature/several-unrelated-fixes/144` (split into separate branches instead)
The real Echologyx ID as the trailing segment	Initials or a GitHub username — the ID is what makes a branch traceable, not a name

Commit conventions

Follow Conventional Commits: type: short summary, written in the imperative mood.

Type	Use for
`feat`	A new section, block, snippet, or capability
`fix`	A bug fix
`docs`	Documentation only
`style`	Formatting, no logic change
`refactor`	A code change that isn’t a fix or a feature
`test`	Adding or adjusting tests
`chore`	Tooling, config, dependency changes

feat: add announcement bar section
fix: correct cart drawer focus trap
docs: document branching and PR workflow

Keep commits small and focused, one logical change per commit.

Add a body when one line isn’t enough. If the change needs explaining, several related pieces, a non-obvious decision, a reason a reviewer would otherwise have to ask about, leave a blank line after the summary and describe it as a bulleted list. Each bullet is one point, in the imperative mood, covering what changed and why:

feat: add announcement bar section

- add auto-rotating web component with reduced-motion support
- expose per-message colors as sol palette variables so they follow the theme
- add padding and mobile-padding settings per project conventions
- use aria-live="polite" so screen readers announce each rotation

Rules of thumb: keep the summary line under ~72 characters, don’t repeat the summary in the body, and explain the reasoning rather than restating the diff, the diff already shows what the code does.

More examples, right and wrong

✅ Good commit message	❌ Weak commit message	Why
`fix: refresh cart total_price on quantity change`	`fix bug`	Specific about what and where
`feat: add nestable "quote" theme block`	`updates`	Says what was actually added
`refactor: extract product-card snippet shared by grid and search`	`cleanup`	Explains the actual change, not just the category

A separate, optional feature: Shopify’s GitHub theme sync

Shopify also offers a GitHub integration that can connect a branch directly to a theme in your store: pushing to the branch updates that theme automatically, and editing the theme in Shopify admin commits those changes back to the branch, authored by the shopify bot. This is a real Shopify platform feature, but it’s a separate decision from the branching and commit conventions above, and nothing in Solis’s own README or docs currently describes the team using it. Confirm with the project maintainer whether a given branch is actually connected to a theme before assuming either direction of the sync applies to your work.

If a branch is connected, two things follow directly from how the sync works:

Admin edits create real commits, so expect to see shopify-authored commits mixed into that branch’s history, not just your own.
Avoid rewriting history (git rebase -i, force-push) on a connected branch. Shopify’s sync depends on a steady, unchanged commit history to line up admin-side changes correctly. This is a narrower, mechanical reason, distinct from Merging’s general “we don’t rebase” policy for PRs.

See Shopify’s GitHub integration for themes for how the feature itself works, and don’t assume it’s in use on a given branch without checking.

Do / Don’t

✅ Do	❌ Don’t
Name every branch `type/short-description/echologyx-id` right from the start.	Using a commit-type word for a branch where it doesn’t fit, or vice versa. They’re separate vocabularies on purpose.
Write commit messages that would make sense to someone with no context, six months from now. A message like “fix bug” tells a future reader nothing.	—
Confirm whether a branch is connected to a Shopify theme before rewriting its history, rather than assuming it either way.	Assuming Shopify’s GitHub theme sync is in use just because it’s a real Shopify feature. Check with the project maintainer first.

Key takeaways

Branch: type/short-description/echologyx-id — feature, component, bug-fix, config, docs, or refactor.
Commit: type: summary — feat, fix, docs, style, refactor, test, or chore. Add a bulleted body for anything that needs explaining.
Branch types and commit types are separate vocabularies; they don’t have to match.
Shopify’s GitHub theme sync (push updates a connected theme, admin edits commit back) is a real, separate feature, not confirmed as something Solis currently uses. Avoid rewriting history on a connected branch if it is in use.