How do we maintain our codebase
As stated before, at Ionia Management we try to be cutting-edge with our IT stack. But we don’t stop there. After all, the end result of using the IT stack is the codebase, and this is our most important asset (besides people of course). So we take great care in maintaining it properly. Here are the 13 steps that we employ to achieve that.
Everything begins here, so this step is very important. Initially we were using plain-old email for issue tracking. We even implemented a mechanism for automatic ID creation per email message, so we could easily refer to a specific message later. However, email messages can’t be categorised easily. Besides that, email is used for so many other types of communication, thus it’s not reliable as an issue tracker.
Another option we tried was to use Jira, which covers all the necessary functionality. However, we ended up developing our own issue tracking system, for two reasons:
Either way, the main concern here is to collect all information regarding a specific issue (messages and attachments) in a single place, and give it a unique ID. Every time someone wants us to fix a bug or build a new feature, they have to go through our issue tracking application. Having a good system ensures that all issues are carefully articulated and documented, and also provides statistical insights at the end of each year.
2. Specification document
Bug fixing is usually straightforward, but in the case of new features (or obviously, new projects) we have to transform the correspondence submitted to the issue tracking system, into a proper specification document, to be used by the developers. This document should contain ample implementation details, including database design (my favourite part). When the document is ready, we submit it to the issue tracking system as well. Spec writing is an art form in itself, so we are always trying to get better at this.
3. Create new local branch on local development machine
When we finally have our issue and our spec, it’s time to open a new branch to work on. This can be named anything the developer likes, but usually we name it the same as the issue ID.
4. Development and testing on local machine
This is the meat of the process, obviously. We don’t have a QA department, so we try to bring together developers, architects and users, as often as possible, during the development stage.
5. Update documentation
Here is where we are trying to improve. We used to store documentation in our document management system, i.e. SharePoint. But current good practices (I try to avoid the term "best practices") dictate that all documentation should reside in the project’s repository, and be updated along with the code. In our case, this includes the below four documents for each project:
We try to avoid binary formats. All documents should be text-based, so they can be tracked and versioned by git. In order to support images and formatting in the documents, we use open markup technologies (currently HTML, and in the future Markdown) so the documents can be rendered properly when needed.
Recommended by LinkedIn
6. Commit
This is self-explanatory. We are just making sure to include the issue ID in each commit message, along with a short description. The only comment I would like to add here is something I recently read: "the commit is our principle unit of work. It deserves to be treated thoughtfully and with care."
7. Git push to new remote branch
Self-explanatory as well. Just a quick note: when a "git push" of a new local branch is executed, a new remote branch is created automatically (provided that the developer has permission to do so).
8. Create pull request
This is important. It signifies that the developer is confident for his work, and is ready to submit it for code review. Again we include the issue ID in this step, so we can easily refer to the respective issue later.
9. Merge pull request
This is the code review step, usually performed by the team leader or software architect (that would be me, in most cases). If all the previous steps have been performed diligently, then this step is mostly a formality.
10. Delete new remote branch
After merging the pull request, the new remote branch can be safely deleted. Github offers this functionality by default. In the end, you will have your new commits plus one more (named "merge…") on the remote main branch.
11. Git checkout main and git pull on local machine
This pulls all new commits, so there’s no need for "git merge".
12. Delete new local branch on local machine
At this stage, the new local branch can be safely deleted as well.
13. Deployment: git pull on server
This is the 13th step, but hopefully it’s not bad luck. We just perform a "git pul" on the deployment server, and normally the new changes are automatically read, without needing to restart the application. This holds true for both Django and React apps.
Maintaining a good codebase is key in the success of a development department. Following the above steps, and at the same time improving the process continuously, we are hoping to be in a good position for many years to come.