Methodic operation with source control and issue tracker system for better results

Software development with multiple groups can be a very challenging operation that requires a lot of visibility between co-workers and development teams and groups. Everyone does his or her very best to provide an operational software component. However, adjustments always have to be made.? As the product evolves, so do these software components have to grow or replace new ones. Customers sometimes surprise the development teams with the ways they work with the product exposing the development teams to completely new scenarios they never considered. So as the development of the code progresses, developers will always have to go a few steps back to understand the code and what was implemented in the past before they change it and add more code of their own.

The average developer pushes between 3-5 commits per day. Multiply it by the number of developers working on the code and the number of days that passed since the code only printed “hello world,” you will get a considerable amount of code with thousands of commits. As stated, developers will have to go back and understand what was done to know how to advance - it’s like dancing. When you deal with an enormous code base, trying to find the code that does something particular is like trying to find a needle in a haystack. Especially in large companies where many people contribute to the code, and some change positions or move on, finding the relevant person to guide you also becomes challenging. Hence it is you against the code.

Any developer with enough persistence will eventually find the related code, understand how it works and figure out a way to extend it or replace it to comply with new requirements. The developer could add printouts within the code or use debug techniques to perform a re-engineering work and only then continue with the new development. Methodic operation with source control and issue tracker system, all developers could minimize the time required for code study, move faster to the development phase and get better results.

Best practices in Issue tracker systems

There are various issue tracker systems in the market, such as Jira, Backlog, Trac, Redmin, WebIssues, Asana, Monday, etc. Each issue tracker system has its own price tag, pros and cons. The document would focus on Jira as a highly respected issue tracker system, but all principles can be applied to other systems as well. Jira is a collection of issues structured and categorized. The Jira issues could be bugs, user stories (a complete implementation), epics (collection of user stories), and sub-tasks (breakdown of the work).

The team, including the developers, quality assurance, customer delivery, product owners, and product managers, must work together and interact, giving feedback to each other at all levels. Though product managers would write epics, product owners would write user stories, customer delivery, quality assurance would report bugs, and developers would write subtasks, insight and feedback from all levels can help everyone provide higher quality issue tracker content.

Epics and Product Managers

Employees who define the product's behavior can be considered product managers; therefore, you do not necessarily have to hold the title. Product managers are the ones that have to communicate with customers and articulate a specific behavior the product should follow. This behavior can be anything from a feature, performance improvement, or documentation (yes! Documentation is part of the product.) The product manager should open an Epic issue specifying the entire requirement. The specification can be written within the Epic issue body or a link to an external document.

It is essential to define the scope of the epic to a very concrete specification that does not take too long to implement. What is too long to implement? The rule of thumb would be the time it takes to work and deliver a new release.?

It is essential to break down the roadmap into epics. Some epics may depend on other epics, or as developers like to put it, a DAG (Directed Acyclic Graph) of Epics. The Product Manager would decide which epic takes priority. It is crucial not to piggyback on a specific epic and extend it with new work - separating the work into chunks is very important. The product manager does the initial breakdown of the work into epics.

Product Managers must have a clear view of what is out there in the market: Who are the customers? What are they looking for? What is important to them? What are the upcoming trends? The role is tightly linked to marketing.

User Stories and Product Owners

There is an unclear line between Product Managers and Product Owners, and in various companies, the separation may be different, and in some, it will be the same person. Product Owners interact strongly with the Product Manager and with the development teams. They have a more technical-oriented view. The Product Owner will take each Epic and break it down into User Stories. A User Story is a minimal amount of work required to complete functionality from end to end.

The User Stories within the epic might also have dependency between them. One User Story might be dependent on another. We again get a DAG of User Stories within each Epic, and the Product Owner, together with the development teams, decides who should do what and where. Here there are several approaches: working in sprints or working in Kanban.

Bugs from Customer Delivery and Quality Assurance

Quality Assurance is an operation performed by the development team to check itself. Everyone within the development team must do Quality Assurance. I can be reinforced by dedicated people who perform manual tests or build automated testing systems. Sometimes User Stories could be dedicated to upgrading the automated testing systems or to performing manual test cycles. When Quality Assurance activity identifies a problem/bug, it should be introduced as a Bug issue.?

Customer Delivery usually assists customers with technical problems and guides them on making the most of the product. However, sometimes the customer exposes issues that Customer Delivery translates into Bug issues. These issues are unusually more complex and occasionally related to conditions nobody within the firm considered. These issues will be reported as Bug issues. These issues can lead to new Epics. Everyone in the firm can learn a lot from these Customer Delivery issues.

Bug issues should be updated continuously as more information pours in until it is resolved. Sometimes the Bug is only a side effect of a completely different problem. It is essential to understand at the end what was solved.

Subtasks and Developers

It is the final breakdown. Developers handle User Stories and Bugs. Several developers may require to address the same issue in different components within the code.? The work could be divided using Subtasks. The same developer might find it easier to break down the job into several Subtasks.?

Best practices in Source Control systems

Git is the most popular version control system, with 89.17%. Svn is the second most popular version control system with approximately 9% market share. In Git, the most common hosting providers are GitHub and GitLab. The hosting providers provide a nicer UI to interact with Git with the ability to interact with team members regarding the code. This document will focus on Git.?

Git is composed of commits. Each commit is an update within the code that may include new files, updated files, deleted files, and also renamed files. A sequence of commits composes a branch. A branch may have several branches that branch out and may merge back to the original branch. Each branch has a name, and every commit has an ID and a message explaining the commit. For more information about Git structure, go to https://git-scm.com/.

Best practices with branches - Cactus branching model

Main Branch

The master branch should be the main branch containing the most up-to-date and stable code.

Version Branch

Version branch branches out of the main branch - It should be given the version's name. Every version much have a separate branch in case of a Hot Fix is required - A Hot Fix is a fix on a given version without releasing a new version.

Epic Branch

Epic branch branches out of the main branch - It should be given the name of the Epic Jira ticket identifier and a short title in the format: epic_<Jira ticket Id>_<title>, for example, epic_PD-101_MyFeature.

When the development on the epic branch is complete, it should be merged back into the master branch.

User Story Branch

User Story branch branches out of the related epic branch. It should be given the User Story Jira ticket identifier and a short title in the format: us_<Jira ticket Id>_<title>, for example, us_PD-102_MyFeatureStepOne.

When the development on the user story branch is complete, it should be merged back into the epic branch.

Bug Branch

Bug branch branches out of the master branch. It should be given the name of the Bug Jira ticket identifier and a short title in the format: bug_<Jira ticket Id>_<title>, for example, bug_PD-103_MyBug.

When the development on the bug branch is complete, it should be merged back into the master branch.

A bug can be a Hot Fix. In that case, the bug branch branches out of the version branch. It should be merged back to the version branch and cherry-picked to the master branch.

Best practices with commits - every commit has a home

Each commit must include a message that mentions the related Jira ticket, whether the ticket is a User Story, Bug, or Subtask. The message should be in the format: [<Jira ticket Id>] <short explanation>, for example, [PD-104] adding helper functions.

Every commit and every branch references a specific Jira ticket providing context to the short information within Git. When people read the git log, it is easier to identify what commits were related to which issue.

Pitfalls

Developers must avoid performing a commit not associated with a Jira ticket. It is sometimes a bother to find or set up the Jira issue related to the wished commit. Once developers do not make the effort to modify the Jira or to motivate others (product managers, product owners, customer delivery, or quality assurance), the Git history becomes less readable, and it is harder to understand the purpose of the commit or how it fits in the big picture.? The same applies to branches - branches must be associated with an Epic, a User Story, or a Bug.

Developers must not use the same Jira ticket to push commits that are not related. This causes context problems - The issue was assumed to be associated with a specific Jira ticket, but it was not.

These problems are usually caused due to high pressure and the drive to move quickly. Working not according to the defined method would cause delays later ahead. This should be the drive to work methodically, even under enormous pressure.?

Another workaround development teams might do is to create a dummy Jira ticket with a general name. This Jira ticket becomes a placeholder for urgent development tasks, tasks without time to find or create a proper Jira ticket.

Another action to avoid is to perform a commit directly on the master branch however small the commit might be.

Summary

With a well-maintained Issue Tracker system and a well-maintained Git repository, we get a low-level design tapestry of the product on the Issue Tracker system and a mirror image in the code. Everyone must be involved in grooming the Issue Tracker system, from product managers and Product owners through customer delivery to developers and Quality assurance engineers. Developers must create branches and commits that form a mirror image of the Issue Tracker system. It does not mean that things will be simple, but it will help everyone find their way around the code quickly. Though it requires some hassle and attention, it will be beneficial in the long run. This is highly recommended to emerging teams both in corporates and in startups.