Branching flow

Reading time: 5 minutes

This document outlines the branching (and development) flow for our project, which includes three main environments:

• develop (Mars)
• pre-release (Venus)
• master (Production)

Additionally, there's an automatic pull-request preview environment:

• pluto

This is generated upon pushing a branch with a "feature" or "fix" prefix.

---

Following these guidelines ensures an efficient development process, prevents release conflicts, and maintains a clean project history. This aids in debugging and tracking code versions and by that, we can maintain a well-organized and efficient branching flow, ensuring that our codebase remains clean and easy to manage while minimizing the need for rollbacks.

1. Branching

Creating feature/fix branches:

Use this naming convention for branches:

[prefix]/[ticket number]-[short description]

✅ Do this	❌ Don't do this
feature/1445-submit-button-disabled	feature/submit-button-disabled
feature/1371-disable-popup-for-teacher	feat/disable-popup
fix/1420-cheat-detection-back-button	fix/button-problem

• Start by creating a feature or fix branch from the up to date develop branch.
• ⚠️ Avoid mixing multiple tickets within one branch. Follow this simple rule: "one ticket - one branch". The only exceptions are truly minor changes (e.g., tiny style or color changes, renaming some local variable, etc.) You can make small adjustments within the same branch. For significant changes (or things you found that could be improved while working on something else), create a new branch to maintain a clean commit history.
• You have the freedom to push multiple commits and name them whatever you like. Frequent commits on YOUR branch are encouraged.
• You can push and create PR with your feature branch even if it is not ready but mark it as draft.

2. Merging branches and Pluto

After completing your feature, you can access Pluto (feature preview branch). A Pluto branch is created every time you push things to the remote of your feature branch.

Once satisfied with the feature (after completing it and testing on your own on the feature branch) you can share the Pluto URL for testing and mark this branch as ready for review (by sending it to the development-team channel on Slack).

1. Assign yourself to the branch in the GitHub.
2. Mention the ticket number in the description and on the right sidebar of the pull-request view.
3. Upon review and approval, Squash and merge the branch into develop.

⚠️ Important ⚠️

Squash all the commits into a single commit for better Git history management. Follow conventional commits convention when doing this step

https://www.conventionalcommits.org/en/v1.0.0/#summary

Below are some examples of good squashed commit names:

✅ Do this	❌ Don't do this
feat: add disabled state for submit button	feat: submit button disabled
feat: disable answer pop-up for teacher user account	feat: disable popup
fix: breaking cheat detection state when using the back button	fix: back button problem
fix: cheat detection logic with back button	fix: cheat detection
fix: condition for sending request when clicking back button in cheat detection mode	fix: issue with request
fix: cheat detection model for notifying when the user exits exam	fix: fixed cheat detection issue
style: update sign in button backgroundColor	fix: change sign in button color
chore: update Swedish locales for sign in button	fix: change i18n typos for button

You can also mention the ticket number in the squashed commit if you wish:

• feat: 1445
• feat(1445)
• feat: [1445]
• feat[1445]

but it is not mandatory since it is easy to track down which branch was responsible for this ticket and this info should already be included in the pull-request description.

Squashing helps identify specific feature changes easily in the history or cherry-pick this one specific feature if we need to remove it from the app.

3. Releasing to environments

The flow when releasing changes is really simple:

1. Feature/Fix branch -> develop
2. develop (Mars) -> pre-release (Venus)
3. Pre-release (Venus) -> master (Production)

• To release to the pre-release environment (Venus), create a pull request develop (Mars) to pre-release (Venus).
  

• To release the production, create a pull request pre-release (Venus) to master (Production).

Click Merge pull request to include all the commits. The best option would be to rebase locally and push to avoid merge commits, but it is totally fine to create merge commit. (Using "Rebase and Merge" on Github will generate new commit SHAs - it is similar to rebase with --no-ff option and even when the commit is up to date, a new commit will be introduced instead which is super annoying and creates unecessary mess.)

Beside that you have to release it to server. Reach out for help with setting up Termius and getting .pem keys to be able to do that.

⚠️ Important ⚠️

Do NOT squash or rebase and merge on this step. You should only squash when merging YOUR feature branch to develop.

Production release

When releasing to production, ensure to create a draft and add a tag following semantic versioning in GitHub.

1. Go to Releases
2. Click "Draft a new release" and select target branch to "master"
3. Create a new tag following https://semver.org/
4. Click "Generate release notes" to generate some release descriptions. GitHub will automatically include what new commits are included in the release.
5. Clean up generated release notes if necessary (remove any release or merge commits - but there should not be any). Follow this pattern for the release notes: Example Release Notes

4. Rollbacks

• Avoid rollbacks whenever possible, as they can create problems with development and branch cleanup.
• Do not roll back for minor issues such as misaligned CSS or incorrect colors. Instead, create a new branch from develop and just run this through the flow.
• If there are any critical issues with the production release and you know for sure why it breaks or what is missing, create a hotfix directly in the production environment. Create a new branch from master with hotfix/description and test it on the Pluto branch. After testing, merge it into the master branch.
• Remember to sync branches from the top down after hotfixes (merge master to pre-release, and develop) to maintain consistency and avoid unsynced branches.

---

Note

Please note that while these guidelines offer a structured approach to development, they are intended as recommendations. I trust that the individuals working on the project possess the logical skills and judgment to adapt when situations call for a different approach if needed so these instructions should not be blindly followed and should rather be treated like recommendations.