Branches

Proper branch naming and organization are essential for maintaining a clean, efficient workflow. Consistent branch names make it easy to identify what each branch does, link it to specific tasks, and understand its purpose at a glance. This organization prevents confusion when multiple team members are working on different features simultaneously, ensures a smooth code review process, and helps maintain a clear project history that’s easy to navigate and manage. This branch strategy is inspired by Github Branching Name best practices.

---

Main branches

• main → Main branch, represents the production state.
• stage → Staging branch, used for testing and integration before production.
• dev → Represents the dev state of the project.

Important

We use these main branches to deploy to their corresponding environments.

This means:

• The dev branch should reflect what is deployed in the Dev environment
• The stage branch should reflect what is deployed in the Stage environment
• The main branch should reflect what is deployed in Production

Keeping branches aligned with their environments helps avoid inconsistencies, deployment issues, and unexpected differences between environments.

---

Naming convention

Each working branch follows this format:

<keyword>--<description>--<clickup-id>

Example:

feature--post-salesforce--86dxq5zn6

Keywords

Keyword	Recommended use
create	Add a new module or page
feature	Integrate a third-party service or add an endpoint
fix	Bug fixes
refactor	Code restructuring without changing functionality
design	Visual or design changes
test	Add or modify tests

Description

• Use kebab-case (lowercase with hyphens).
• Keep it short and descriptive.
• Avoid spaces, accents, or special characters.

ClickUp ID

• Add the ClickUp card ID at the end for task tracking.
• Example: --86dxq5zn6

Example branch names

create--module-cta-aninmated--86dxq5zn6

feature--post-to-salesforce--86dxq5zn6

fix--error-slider--86dxq5zn6

refactor--php-8-compatible--86dxq5zn6

design--update-header-spacing--86dxq5zn6

test--animation--86dxq5zn6

---

Step by Step workflow

Important — Please read before continuing

It’s extremely important that everyone working on a project understands and follows this branching workflow.

This process exists to keep the team aligned, avoid stepping on each other’s work, and reduce unnecessary mistakes. Issues will happen — that’s part of development — but they shouldn’t happen because the workflow wasn’t understood.

If something in this process feels unclear, stop and ask before moving forward. Being aligned here saves time, avoids conflicts, and makes collaboration much smoother for everyone.

1. Create a branch from main using the naming convention above: Example: fix--cardE--86XXXX
2. Make your changes and verify everything works locally (tests/build/lint as applicable).
3. Pull request of the dev or stage branch (whichever environment you’ll work) so you have the branch updated with the latest changes.
4. Merge fix--cardE--86XXXX into branch dev or stage (depends of the needs) via merge process.
5. Deploy to the Dev/Stage environment and validate the changes there.
6. Is everything OK in Dev/Stage?
   • If no → fix issues on the same branch (fix--cardE--86XXXX) and repeat steps 2 to 5.
   • If yes → continue.
7. Update your branch with the latest main. For that:
   • Switch to your branch fix--cardE--86XXXX
   • Pull latest main.
   • Merge main into your branch.
   • Verify again (tests/build).
8. If all is OK, merge your branch into main.
9. Deploy to production.
10. Delete the working branch fix--cardE--86XXXX.

---

Do’s and Don’ts

✅ DO	❌ DON’T
Use the format keyword--description--clickup-id	Create branches without following the naming convention
Use clear, short, kebab-case descriptions	Use spaces, uppercase letters, accents, or special characters
Always include the ClickUp card ID	Skip the ClickUp ID or use an incorrect one
Create your working branch from main	Start working directly on main, stage, or dev
Keep branches focused on one task	Mix multiple unrelated changes in one branch
Merge your branch into dev or stage for validation	Merge directly into main without prior validation
Make sure dev, stage, and main match their environments	Let branches drift from what’s deployed
Update your branch with the latest main before final merge	Merge outdated branches into main
Test your changes locally and in dev/stage	Deploy without testing or reviewing
Keep every main branch separate	Merge stage into production
Delete your branch after it’s merged and deployed	Keep old branches after the work is done
Ask for help if you’re unsure about the flow	Guess or improvise with merges and deploys

---

Video

It’s important to watch this video to have full context of the explained topics. If the video doesn’t load or stops with an error, you can watch it directly on Loom.