Quick guide on how to create the IT infrastructure and start delivering your product
You are with a lot of projects in your head and one day you decide to sit for a moment and start to evaluate which ones could really turn into something… You start planning how your preffered project would be, write a few use-cases— perhaps a few mockups if you’re that enthusiastic — and finally you want to give life to this promissing project.
When that beautiful moment of action arrives, you’ll end up needing a place to code, a bucket to store your bits, a board where you define your tasks and their priorities, multiple environments for different code stages, databases for each environment, and so on.
That’s why I’m writting this article; to share with you the steps I go through everytime a new promissing project pops in my head :-D
Writting your tasks and assign priorities
90% of the time, my first drafts are on paper. It gives my imagination more freedom while I’m brainstorming. When I believe there’s enough to start working, I usually create a Jira board (there are a lot of other similar platforms like Trello or Asana). In this board, is where I create a ticket for each task I have to do. On it, I describe the task and I give it a status which will be updated everytime it progresses. I also like to add attachments and comments so my team and me can track better what each one of us has been doing and the stage of each task.
When the use-cases involve a lot of tasks, I like to create, what it’s called on Jira, an “Epic” ticket. In this tickets, I describe the use-case and I associate all the tasks related to that use-case, under it. It keeps the board more neat :-)
To not forget that on each task/epic ticket, you can specify it’s priority and move it up and down the board according to your needs.
How many environments should I be working on?
This is a frequently asked question and my answer is… it depends! For smaller projects we normally work with 4 environments: DEV, UAT (User Acceptance Tests), BENCH and PROD.
On bigger projects that may need multiple teams working on multiple modules, I suggest to create an UAT environment for each team so all of the teams can have a bit more of independency (ex.: UAT1, UAT2, …).
Environments and task stages
There is a strict relation between environments and the stages where a given task is at a specific moment.
When a developer has a new task to code, the first version (rarely the final version) is deployed to the DEV environment where he/she can test if the changes made are working properly.
If the code is working as it should in DEV, it’s now time to deploy it on the appropriate UAT environment so one of the testers of your team (or even you) can demonstrate the new funcionality/bug fix to the final user.
When the change is approved by the client, it’s when we receive green light to move it to Production! Although, before we deploy the code to PROD we should test if the changes made interact well in an environment very similar to PROD, which is BENCH. This environment only contains the developments that PROD already has and the new ones that are to be released in the new version. This way we can predict any problems that could happen when integrating the new version into Production and avoid all the consequences that could have to your clients.
Branches
When deploying a new version for a given environment, this environment needs to know in which repository the code for that specific environment is. For that, since we have DEV, UAT, BENCH and PROD environments we also have DEV and UAT branches. For BENCH and PROD, we have a different name for that branch, which is HOTFIX and is common to both environments. Besides those branches, we also have the master branch — the base on which new developments will rely on.
It is also recommended that you create a new branch for every task that you are coding. If you are coding a new feature for task “SMART-44” (using the example on the picture above), you should create a new branch with that name “SMART-44” and develop your code on it.
The roadmap on each branch
Now I will try to explain why we use the branches we use.
When we finish coding for our task, we commit the changes and push them to the specific branch of the task we’re working on. Then, we merge that branch into DEV. If, at this step, Git shows us a message telling about a conflict, it probably means that someone also merged their commits to DEV and we both changed the same file. Git doesn’t know which version will prevail. To solve this, we can check the logs of the merges into DEV and find out which commit is giving the conflict and decide which task should move on firstly to Production. Why? Because we’re going to need to merge the most prioritary ticket into the less prioritary, in order to stop them from conflicting. When we do this, we flag the Jira ticket telling that one task depends on the other task and a link is created between those two.
Then, we merge both tickets into DEV again and this time the merge should go perfectly!
We are ready to deploy our DEV branch on our DEV environment and test what we’ve done so far.
When we are ready to show our masterpieces to the client, we mark the Jira tickets with a Target Delivery flag “UAT” and change it’s status to “Waiting UAT Delivery”.
When the deploy to UAT is triggered, we have a bash script to delete the current UAT branch and search for all the Jira tickets with Target Delivery flag “UAT” and merge each on of them into a fresh UAT branch. This way makes it really easy to put on and remove tickets from UAT environment.
This script also updates the status of each of the Jira tickets, that have been deployed to UAT, to the “UAT Delivered” status. Which will also be changed to “UAT in Progress” when the tests on it begins. When they are done, we move it to “UAT Done”.
At this stage, it means that our development is working fine (at least nobody found a bug so far) and it is ready to move to Production. But as I wrote before, it needs to pass through BENCH environment before it can move to PROD.
In order to do that, there’s a single change that needs to be made. Changing the Target Delivery flag to “HOTFIX” and the process behind the HOTFIX branch is the same as the UAT one: when deploy is triggered, a new branch is created with all the tickets flagged as HOTFIX. Status is now “Bench Delivered”.
I didn’t mention before, but for a deploy to occur — which is nothing more than copying files to a specific environment directory — the package containing the new code needs to be built! So for a new version to be released, a new build has to be generated and then a deploy of that build.
So, when everything is tested in Bench and the status moved to “Bench in Progress” and then to “Bench Done”, we trust that the build used in BENCH is safe to go to PROD. We use the same package that the build generated and deploy it to PROD. Status is then changed to “Closed” and Fix Version is updated with the version that has just been released.
At this moment, our tickets are in Production and can be used by our dear clients :-D
Now it’s time to update our master branch, the base for new developments, with the last version, that is in HOTFIX. For that, we can or merge HOTFIX into master or clone HOTFIX as master.
Tools used to orchestrate builds and deploys and execute scripts
We have a lot of stuff that have been automated with the years which not only saved us our precious time but also saved us from human errors.
Git
We created an alias to a bash script that basically is a menu with 3 options: Create branch, Push to branch and Merge to DEV.
These are the actions we use the most and it’s so much easy to just call this alias and type the number of the option than to type the sames git commands everytime. Although, some commands like git add and git commit are still manually executed for a better tailored execution.
Jenkins
Jenkins is awesome! It is where our scripts are called and where you can orchestrate their execution. We have a few jobs: Build Project, Deploy Project, Build & Deploy Project, Start and Stop Project, etc.
It is very convenient and there are a lot of plugins available to be used with it, like sending e-mails when errors occured during a build or when a new version is deployed. If you never tried it, I definitely recommend you giving it a try.
And that’s it! I tried to tell you in a simple way the infrastructure that I am using because I think it’s very easy to implement and nice to work on. Please let me know if you have any question or suggestion at any point. I would be more than happy to have your feedback!
