Skip to main content

Git Workflow

This document outlines our Git workflow standards at Kirana Labs, ensuring consistency and quality across all projects.

Branching Strategy​

We use a branch-based workflow centered around the dev branch:

Main Branches​

  • main: Production-ready code

    • Always stable and deployable
    • Direct commits prohibited
    • Only merged from staging via PR

  • staging: Pre-production testing environment

    • Integration testing and client approval
    • Only merged from dev via PR

  • dev: Development branch

    • Integration branch for features
    • Always contains the latest development code
    • Feature branches are created from and merged back to this branch

Feature Branches​

  • Create a new branch from dev for each feature or bug fix
  • Follow naming convention:
    • feature/KL-123-short-description
    • bugfix/KL-123-short-description
    • hotfix/KL-123-short-description (for urgent production fixes)
    • refactor/KL-123-short-description
    • docs/KL-123-short-description
  • KL-123 refers to the task ID in Plane

Step-by-Step Development Process​

1. Assign Task​

  • Task is assigned during sprint planning
  • Developer accepts the task in Plane
  • Move the task to "In Progress" when starting work

2. Create Branch​

# Ensure dev is up to date
git checkout dev
git pull origin dev

# Create a new feature branch
git checkout -b feature/KL-123-user-authentication

3. Make Regular Commits​

  • Make small, focused commits
  • Follow commit message standards: 
    KL-123: Add user authentication form

    - Create form component
    - Add validation
    - Implement auth service integration
  • Push changes to remote regularly: 
    git push origin feature/KL-123-user-authentication

4. Stay Updated with Dev​

  • Regularly pull changes from dev to stay updated: 
    git checkout dev
    git pull origin dev
    git checkout feature/KL-123-user-authentication
    git merge dev
  • Resolve any merge conflicts

5. Create Pull Request​

  • When the feature is complete, create a PR to merge into dev
  • Fill out the PR template with:
    • Summary of changes
    • Testing performed
    • Screenshots (if UI changes)
    • Checklist of completed items

Git Commit Guidelines​

Commit Message Format​

<task-id>: <subject>

<body>

<footer>

Examples​

KL-123: Implement user authentication form

- Add email/password form with validation
- Connect to auth API
- Add Remember Me functionality
- Add error handling for invalid credentials

Closes KL-123
KL-456: Fix pagination bug in product list

The product list was not respecting the page size parameter,
always defaulting to 10 items regardless of the setting.

Fixed by properly passing the pageSize param to the API call.

Fixes KL-456

Best Practices​

  • Keep subject line concise (50 chars or less)
  • Use imperative, present tense in subject line ("Add feature" not "Added feature")
  • Reference the task ID at the beginning
  • Provide detailed description in the body
  • Separate subject from body with a blank line
  • Use bullet points in body for multiple changes
  • Add "Fixes" or "Closes" followed by the issue number in the footer

Git Workflow for Specific Scenarios​

Handling Urgent Production Fixes (Hotfixes)​

  1. Create a hotfix branch from main: 
    git checkout main
    git pull origin main
    git checkout -b hotfix/KL-789-critical-bug
  2. Fix the issue with minimal changes
  3. Create a PR to merge into main
  4. After merging to main, cherry-pick the changes to dev: 
    git checkout dev
    git cherry-pick <commit-hash>
    git push origin dev

When multiple developers work on related features:

  1. Create a base feature branch: 
    git checkout dev
    git checkout -b feature/user-management
  2. Create individual branches from the base feature branch: 
    git checkout feature/user-management
    git checkout -b feature/KL-123-user-creation
  3. Merge individual feature branches back to the base feature branch
  4. Finally, merge the base feature branch into dev

Cleaning Up Branches​

Regularly clean up merged branches:

# Update remote tracking info
git fetch --prune

# List merged branches
git branch --merged dev

# Delete a local branch
git branch -d feature/KL-123-completed-feature

# Delete a remote branch
git push origin --delete feature/KL-123-completed-feature

Git Tools and Configuration​

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@kiranalabs.com"

# Set default branch to main
git config --global init.defaultBranch main

# Setup helpful aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate"

Useful Git Commands​

# View status
git status

# View commit history
git log --oneline --graph --decorate

# Stash changes temporarily
git stash
git stash pop

# Discard changes to a file
git checkout -- filename

# Undo last commit but keep changes
git reset --soft HEAD~1

# Amend last commit
git commit --amend

GitHub Integration​

PR Template​

## Description
[Describe the changes made in this PR]

## Related Issue
Closes KL-123

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Refactoring
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] E2E tests added/updated
- [ ] Manually tested

## Screenshots
[If applicable, add screenshots]

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] New and existing tests pass locally

GitHub Actions Integration​

We use GitHub Actions for:

  • Running tests on PRs
  • Linting code
  • Building applications
  • Deploying to environments

By following this Git workflow, we maintain a clean, trackable history of changes while ensuring code quality across all Kirana Labs projects.