by Horatiu Dan
This post briefly outlines a simple, yet clean process for managing the releases of an application via Git / GitHub. Its goal is to provide a straight-forward recipe, while it is assumed the fact that these practices may vary from situation to situation, from team to team, from project to project.
Set-up
The subject is a small project whose source code resides in GitHub. Details on how it was created and synced into the source repository may be found here (Starting an Angular Project).
The application main branch is https://github.com/horatiucd/ninjago-front-end. The current state of this branch might be different now as the project has evolved.
Creating a Release
Assuming the current state of the application’s main branch is in line with what was aimed to be its first version, the following operations may be done in order to be ready to release it:
- a new branch is created from main – v1.0.0 – and checked out.
> git checkout -b v1.0.0
From now on, this branch will be the ‘source’ of version 1.0.0 releases. Moreover, it will help when fixing issues (bugs) or adding enhancements for this version.
- sync the branch to GitHub
> git push origin v1.0.0
- create a new tag having as target the v1.0.0 branch – release-v1.0.0.
This may be done in two ways, either from the IDE and then pushed to the remote repository or created directly in GitHub. In the former case, the tag is available among the GitHub Tags section and may be used when a release is created.
- create the actual release, provide a name in accordance with the convention used and details on what this version actually contains
Once this is fulfilled, an archive file (zip and tar.gz) containing the project code is available – ninjago-front-end-release-v1.0.0.
- publish the release
The newly made release is visible in GitHub – releases section.
Application Evolution and Maintenance
In case an issue is discovered or an enhancement is wanted in a certain version (e.g. 1.0.0), the recommended approach is the following:
- make the code modification(s) in release branch (e.g. v1.0.0)
- merge the modification(s) into main and all newer version branches
- release from each version branch as desribed in the previous sections
As the main branch is usually the most current one, in case a new version is wanted to be released, the steps mentioned above are applicable.
Use-case
- main evolves
- a fix is needed in v1.0.0
- the fix is done and a new release is made – release-v1.0.1
- the fix is ported to the main branch as well
Use-case log of actions
- the main branch is being modified, the application evolves – this is an ongoing action
- at some point, a bug is found in version 1.0.0 – e.g. the main page should display ‘Ninjago App is running!’ instead of ‘Ninjago App app is running!’
- create an issue branch from v1.0.0 one and check it out
> git checkout -b issue1-v1.0.0
- fix the issue, commit to local branch, push to remote repository
> git commit -m "Fixes the display issue in the main page." > git push origin issue1-v1.0.0
- create a Pull Request in GitHub – from issue1-v1.0.0 towards v1.0.0
- have the changes reviewed and approved
- merge the pull request into the v1.0.0 branch – easily doable from GitHub
- make a new release from v1.0.0 branch
Follow the steps indicated in the above section:
- checkout v1.0.0 branch
- create a new tag on branch v1.0.0 – release-v1.0.1
- create and publish the actual release – Ninjago v1.0.1
- local and remote issue1-v1.0.0 branches may be now deleted
- merge the fix into the main branch so that the next versions will be up-to-date (either by cherry-picking or merging) and push the changes to the remote repository
> git checkout main
> git cherry-pick 04c97e5dd6c6019d502d94186201493c3020bdf1
or
> git merge v1.0.0
> git push origin main
The visual git log for all the aspects described is below.
Summing Up
Although simple and straight-forward, I find this brief recipe useful especially for small sized projects and teams, but not only. A next step is to find a way to automate the process.
