Cavai Docs

Appearance

Git Workflow Complete Guide ​

This document consolidates all Git workflow practices used in the Cavai product ecosystem.

Branch Naming Convention ​

Use action-based prefixes with kebab-case formatting:

Pattern: [action]-[descriptive-name]

Examples:

  • add-tool-inspector
  • fix-block-visibility-issue
  • improve-block-inspection-visualization
  • refactor-form-input-system
  • update-documentation-structure

Action Prefixes:

  • add- - Adding new features
  • fix- - Bug fixes
  • improve- - Enhancements to existing features
  • refactor- - Code restructuring
  • update- - Updates to existing functionality
  • remove- - Removing features or code

Creating New Branches ​

1. Create Feature Branch ​

bash
git checkout -b [branch-name]

2. Work and Commit ​

Commit changes that make logical sense together:

bash
git add .
git commit -m "Descriptive commit message"

3. Push Branch ​

bash
git push -u origin [branch-name]

Selective Stash Workflow ​

When you have work-in-progress that needs to be split into multiple topic branches:

1. Stash Current Work ​

bash
git stash push -m "WIP: describe what you're working on"

2. Create Topic Branch ​

bash
git checkout -b add-specific-feature

3. Apply Specific Changes ​

bash
git stash show -p | git apply --index

4. Selectively Add Files ​

bash
git add [specific-files-for-this-topic]
git commit -m "Add specific feature"

5. Reset Unwanted Changes ​

bash
git checkout -- .

6. Repeat for Additional Topics ​

Return to main branch and repeat process for other features.

Release Workflow ​

Release Command ​

bash
npm run release

Process:

  1. Run the release command
  2. Follow interactive prompts for version bumping
  3. Review changelog updates
  4. Complete publishing steps as guided

Rollback and Re-run Workflows ​

When to use: Failed workflows or temporary CI/CD issues

Steps:

  1. Go to repository Actions tab on GitHub
  2. Navigate to the specific branch
  3. Click "Re-run all jobs" to trigger all workflow jobs again

Fixing Failing Checks ​

Problem: Checks fail on feature branch because fixes are available on main but not on current branch.

Solution: Update feature branch with latest main using rebase:

bash
git checkout main
git pull
git checkout [your-branch-name]
git rebase main
git push --force-with-lease

Command Breakdown:

  • git checkout main - Switch to main branch
  • git pull - Pull latest changes from remote main
  • git checkout [branch-name] - Switch back to feature branch
  • git rebase main - Rebase feature branch on latest main
  • git push --force-with-lease - Push rebased branch safely

Note: Always use --force-with-lease instead of --force for safety.

Development Workflow with i18n ​

1. Add Internationalization ​

Go to i18n -> en.js and add new terms to the dictionary in the appropriate section.

2. Create Components ​

Check for existing components before creating new ones. Look for reusable patterns.

Example Button Component:

vue
<TheButton
  :disabled="nothingSelected"
  class="copy-tags-button"
  @click="copyTags"
>
  {{ $t('delivery.copyTags') }}
</TheButton>

3. Style Components ​

scss
.download-section {
  display: flex;
  justify-content: flex-end;
  border: 1px dashed tomato;
  min-height: 35px;
}

.download-zip-button,
.copy-tags-button {
  // Move button halfway down
  transform: translateY(50%);
  margin-left: 1rem;
}

4. Implement Methods ​

typescript
async copyTags() {
  let allTags = ''

  this.selectedFormats.forEach((creative) => {
    const { creativeSettings } = this.getCreativeData(creative.id)
    
    const script = makeCreativeTag({
      settings: {
        customTrigger: Boolean(creative.deliveryData.customTrigger),
        customTriggerId: creative.deliveryData.customTriggerId,
        type: creativeSettings.creativeProperties.type,
      },
      fullID: this.$route.params.routeCreativeId.replace(/\d+$/, creative.id),
      stubFile: creative.stubFile,
    })

    const formatLabel = this.getFormatLabel(creativeSettings.creativeProperties.format)
    allTags += `/* ${formatLabel} */\n${script}\n\n`
  })

  try {
    await navigator.clipboard.writeText(allTags)
    this.$emit('tags-copied')
  } catch (err) {
    console.error('Could not copy tags: ', err)
  }
}

Best Practices ​

  1. Branch Names: Always use action-based prefixes with kebab-case
  2. Commits: Make logical, atomic commits with descriptive messages
  3. Rebasing: Use rebase instead of merge to maintain clean history
  4. Force Push: Always use --force-with-lease for safety
  5. i18n: Never hardcode UI text; always use internationalization
  6. Component Reuse: Check for existing components before creating new ones
  7. Code Style: Follow established patterns in the codebase

Troubleshooting ​

Common Issues ​

  1. Merge Conflicts During Rebase:

    • Resolve conflicts in each file
    • git add [resolved-files]
    • git rebase --continue

  2. Failed Push After Rebase:

    • Use git push --force-with-lease
    • Never use git push --force unless absolutely necessary

  3. Lost Stashed Changes:

    • Use git stash list to see all stashes
    • Use git stash apply stash@{n} to apply specific stash

  4. Wrong Branch for Changes:

    • Use selective stash workflow to move changes to correct branch
    • Or use git cherry-pick for committed changes

Internal documentation

Cavai