Branch Workflow

Branch management and workflow

Here, we describe how we handle branches.

🚨🚨🚨 BE VERY CAREFUL WITH PROD BRANCHES. DO BACKUPS BEFORE CHANGING THEM. SEE Docker Deploy FOR MORE INFO.

---

TLDR

1. Merge main into dev
2. Make a PR to merge dev into main
3. Make a PR to merge main into prod
4. On the server's prod branch, run gdiff
5. Backup your current branch: git checkout -b prod_legacy
6. Pull changes: git pull origin prod
7. Build AIKON

---

Bare minimum

Branches

Minimally, an AIKON project should have 3 branches:

* main
* dev
* prod

• main is a stable and functionnal branch
• dev is the local work where you do your work
• prod is the branch of the in-production instance of your AIKON app.

Why and warnings

We have 3 branches and a prod branch because in-production apps often need specific configs related to the server or the AIKON instance. For example:

• a production server may use a proxy that requires specific NGINX configs and Docker options
• depending on the app's language, there are different database migrations.

😰 When merging into prod, be very careful of:

• front/app/docker: the Docker folder. Don't blindly overwrite its comments with what comes from main. It often contains configs specific to the server and to that app instance.
• front/app/webapp/migrations: migrations change depending on the app's language.

Workflow

You work in dev, merge with main once it's done, then merge main into prod and from that put in production.

0. Add the gdiff command to your bashrc. It allows you to compare local changes in a branch with remote changes, before pulling => be certain that you won't create a mess when pulling.

   cat << 'EOF' >> ~/.bashrc && source ~/.bashrc
   function git_branch() {
       if [ -d .git ] || git rev-parse --git-dir > /dev/null 2>&1; then
           local branch_name=$(git branch 2>/dev/null | grep '^*' | colrm 1 2)
   
           if [ -n "$branch_name" ]; then
               echo "$branch_name"
           fi
       fi
   }
   
   alias gdiff='git fetch && git diff $(git_branch) origin/$(git_branch) -- ":(exclude)**/static/svelte/**"'
   EOF

1. On dev, do your changes
2. Merge main into dev once your changes are done (if there are conflicts, they will be in dev and not in main)

   # start from dev and checkout into main
   git checkout main
   # pull
   git pull origin main
   # checkout into dev and merge. if necessary, fix issues.
   git checkout dev
   git merge main
   # push your changes
   git push origin dev

3. Create a pull request to merge dev into main. There shouldn't be conflicts.
4. Create a pull request to merge main into prod. Be careful with conflicts. If there are conflicts, try to fix them locally and not on your prod server.
5. Backup your prod branch (see below)
6. Pull changes into prod on your production server

   # start from your prod branch 
   # make sure you don't do a messy pull
   gdiff
   # pull changes
   git pull origin prod

7. Build your dockers to update your production app. See Docker deploy guide

Backup your prod branch

Before pulling changes on your server, do a backup of the prod branch. Starting from your prod branch,

1. Delete the old backup branch

   git branch -d prod_legacy

2. Create your backup branch

   git switch -d prod_legacy

3. Commit it

   git status  # just to be sure you won't commit any errors
   git commit -am "[PROD] backup current state"

4. Push

   git push -u origin prod_legacy

---

In practice

In practice, we have a lot more branches and AIKON is deployed on several servers. The workflow stays the same:

* *-dev   # all of your dev branches
* main    # your main stable branch
* *-prod  # all of your production instance branches. There is typically 1 prod branch per instance +
1 backup branch

The workflow is the same:

• do your changes in your dev branch
• merge main into dev
• do a PR to merge your dev branch into main
• do a PR to merge main into your prod branch
• backup your prod branch
• pull your prod branches and rebuilt your dockers.

For each *-prod branch, there is a *-prod_legacy backup branch. For example: aikon-prod => aikon-prod_legacy.