Set up an upgradeable repository structure for Web Apps based on templates

• 10 May 2024
• git

The other day I was trying to update a boilerplate template we use on my work and came across an interesting strategy for applying updates they release. Taking into consideration that you write your own code on these templates, updating can be quite a lot of effort, especially from a major version to another. They had written a document where they explain how to do some git magic trickery and thought that since it is not actually something specific to them, I thought that I could try and use it on any other project. I chose this website for that, given I am using a Jekyll template named Chirpy and from time to time they release some nice updates, I thought it would be very useful to apply this strategy.

On this web page project I did set it up from the start and it works perfectly, the only manual work that you have to do is to resolve conflicts on files if there is any, of course this varies depending on the size of the project, the amount of changes both from the template and the ones that you made, etc.

Setting up a new project

• First, create a new repository for your project using the template you downloaded, without any change.
• Add it to source control (like GitHub).
• Push it to the main branch.
• Create a branch named develop from main branch. This branch will be used for your daily development.
• Create another branch from develop branch named original-template or any name that you want. This branch will be used for updating your solution with the latest version of the template.
• When a new version of the template is released, download it and don't make any changes to it.
• Switch to original-template branch in your source control and copy new template version into this branch. I sometimes also delete all the files that are on the branch and copy the template from scratch since there could be some deletions that you want to include on the update.
• Switch to develop branch and merge branch original-template into develop. There will be conflicts, resolve them manually.

That's all. Your develop branch will have a new template version. After testing the changes thoroughly you can merge your develop branch (or release branch if you are using Gitflow) to main to release the changes to production.

The important thing here is, you must not make any changes in original-template branch other than overwriting it with the latest version of the template.