Git Workflow Documentation: master / staging / development Branch Strategy

NOTE:

• Use id with your name to develop feature or merge pull requests, so we have track of who did what things.

Branch Structure

• master: Stable, production-ready code. Only tested and verified features reach here.
  • Can only be merged to master branch initally by Ankit. Later the access will be given to other people, so everyone understand the flow.
• staging: Pre-production branch for testing merged features together before releasing to main.
  • Can only be merge to staging branch initally by Ankit.
  • Later the access will be given to other people, so everyone understand the flow.
• development: Active integration branch for ongoing feature development.
  • Pull request can be merged by any other developer, not who created the pull request.
• feature/*: Temporary branches for individual features, fixes, or improvements.
  • Branch name should start with featue/ then your specific feature name

Naming Guidelines

• Branch names:

  • feature/login-page, fix/token-expiry, chore/update-deps

• Commit messages:

  • Format: <type>: <message>

    • feat: for new features
    • fix: for bug fixes
    • chore: for minor tasks

• Pull Requests:

  • Clear title and description
  • Link issues if applicable
  • Add screenshots/logs if needed
  • Share the path of the url in the UI where it can be tested

Best Practices

• Always branch from development
• Regularly sync your feature branch with development
• Keep pull requests focused and small
• Test locally and on staging before going to main
• Use revert to undo features instead of rewriting shared history

Development Flow

1. Create a feature branch

   git checkout development
   git pull origin development
   git checkout -b feature/feature-name

2. Work on your feature

   • Use meaningful commit messages (e.g. feat: add user login, fix: resolve token bug).
   • Keep commits atomic and scoped.

3. Create a Pull Request to development

   • PR title: Start with feat: / fix: / chore: depending on the change

     • Example: feat: add login API with JWT support

   • PR description:

     • What the feature does
     • Relevant issue/ticket link
     • Any test instructions or special notes

4. Merge to development using Squash and Merge

   • Squash keeps history clean by combining all commits into one.
   • Ensure commit message is clear and concise.
   • Make sure you select Sqash and merge and not the other 2 options.

5. Promote from development to staging

   git checkout staging
   git pull origin staging
   git merge development --rebase
   git push origin staging

   • Make sure the merge happens with the Rebase and merge option and not Merge and commit or Squash and merge

6. Promote from staging to master

   git checkout master
   git pull origin master
   git merge staging --rebase
   git push origin master

   • Make sure the merge happens with the Rebase and merge option and not Merge and commit or Squash and merge

Reverting a Feature

If a feature causes issues after merging to either master or staging, we will follow this:

1. Find the commit hash of the squash merge from the staging history.

2. Revert the specific commit only in development branch:

   git checkout development
   git revert <commit-hash>
   git push origin development

   • This creates a new commit that undoes the feature changes.
   • The revert will flow forward when merged to staging/master using the pull request.

NOTE: Selective Revert Process

Consider this scenario:

• A feature is already merged to both master and staging
• New features have been added to the development branch after the merge
• You need to revert only the problematic feature without affecting other new work

Follow these steps to create a targeted revert:

• Identify the specific feature causing issues
• Create a pull request containing only the revert commit
• Deploy the revert to staging/master independently
• Keep other development work separate until ready for deployment

This allows you to promote the revert first, without waiting for the other new changes in development.

🧱 Scenario

• Your branch: development

• Contains:

  • ✅ A revert commit (say, commit hash: abc123)
  • ✅ A new feature commit (you don’t want to promote to staging yet)

You want to send only the revert to staging, not the new feature yet.

1. Create a new branch from staging

git checkout staging
git pull origin staging
git checkout -b revert-only

This ensures the revert will apply cleanly over the current staging branch.

2. Cherry-pick only the revert commit from development which we want to revert

git cherry-pick abc123

• Replace abc123 with the hash of the revert commit.
• This applies just the revert onto the revert-only branch.

3. Push this branch and create a PR

git push origin revert-only

• Go to GitHub and open a PR from revert-only → staging.

• Use a clear PR title like:

  revert: remove Feature X due to issue #42

• This will safely revert the feature without bringing in unrelated new work from development.

✅ After the revert is merged

Later, when you’re ready to bring in the new features from development, you can do your usual:

git checkout staging
git pull origin staging
git merge development --rebase

If you already cherry-picked the revert earlier, Git will detect it’s already applied and skip it — avoiding duplicates.

🔄 Optional Clean-Up

Once the revert is merged:

git branch -d revert-only     # delete local branch
git push origin --delete revert-only  # delete remote branch (optional)