How to Safeguard Your Business Application with Version Control and Pull Management

Every business application goes through multiple iterations. Many mission-critical systems undergo frequent updates – bug fixes, feature additions, integrations, and more. Keeping a well-maintained history of all of these changes isn’t easy, but it is very necessary for the stability of its infrastructure.

5 Benefits of Version Control and Pull Management

Version control and pull management are essential for managing and tracking changes to code and other digital assets. They safeguard your business applications and empower your team to quickly scale and adapt with new functionality without major concerns about losing significant code when bugs arise. While the benefits are many, there are specifically five of note:

1. Protection of Old Versions

With a complete history of all changes your team makes to your system, including all code and files, you can always revert to an earlier version. This is critical if your team can’t determine what caused a bug or if a new feature doesn’t go well with users.

2. Collaboration Among Team Members

Good version control also empowers developers to work together on the same codebase without deploying conflicting changes. They can see each other’s work and ensure they don’t write incompatible code.

3. Preservation of Code Integrity

When things go awry, your development team can also easily see what lines of code cause issues and remove them. They won’t have to completely revert to an older version and sacrifice other team members’ newly written code. You can also set up permission-based control so that only senior team members can push new code after a thorough QA process. You can eliminate accidental and unauthorized changes.

4. Simplification of Troubleshooting

With a clear record of changes through version control, it’s easier to identify the root cause of issues in your code. If you don’t ship significant changes all at once and stick to small changes launched one at a time, you can quickly pinpoint problematic updates and roll them back.

5. Stronger Deployment Management

Strategic pull request management improves and protects the deployment process as well as code quality. Your developers can review and merge changes before deploying them to production.

A Tested Version Control and Pull Management Strategy

The core of what we do at Soliant is imagine, plan, and build business applications. Following strict best practices around all areas of software development is critical to our success and our clients’. Over the years, we’ve fine-tuned a tested and trusted strategy for version control and pull management strategy. We’re happy to share it with you here.

A Foundation Dependent on Developer Ticket Flow

Much of our process relies on keeping Jira ticket status and assignee current. You should move your Jira tickets through their assigned workflow at each applicable milestone. We recommend keeping your Jira tickets in the board’s correct status column and ensuring the ticket assignee is correctly set to the person with the next actionable task. Tools like Jira, Bitbucket, and more certainly help the version control and pull management process, but if you don’t keep the data within these systems clean, they can do more harm than good.

Requestor Responsibilities

As we mentioned earlier, when covering the benefits of version control and pull management, permission-based roles help ensure trackable code changes. We have processes to facilitate multiple developers working on the same codebase and maintaining a clean code history. Our process follows GitHub Flow and the PR Requestor is responsible for maintaining clear and distinct code branches.

Our required steps for any code change are as follows:

1. Create a Branch

Code branches allow developers to make changes and additions to code without affecting other developers’ work. When created, version control essentially creates a copy of the entire code base in its current state. We have a handful of best practices we follow in this first step:

• Most feature branches will branch from “develop,” but production hotfix branches may need to branch from other sources.
• Branch naming recommendations dictate that branches should be prefixed with one of the following: feat/fix /cdk
• Never start a new one from an unstable branch. Squash any work-in-progress (WIP) commits and stabilize the base before branching from it.

2. Make Your Code Changes

Now, it’s time to apply your intended updates to the codebase within your new branch. We follow these guidelines to streamline this step:

• Try to use similar code from existing (recent) projects as a guideline whenever possible.
• Follow code patterns that already exist in the project codebase for consistency.
• Make relevant commit messages. Describe the change and include the Jira ticket number related to the code change. Commit messages should also be prefixed by one of the following:

[
  'build',
  'chore',
  'ci',
  'docs',
  'feat',
  'fix',
  'perf',
  'refactor',
  'revert',
  'style',
  'test'
];

3. Create a Pull Request (PR)

It’s time to start merging your changes with the main codebase. You start with a pull request. This alerts your team members that your updates are ready for review.

We require a source brand to follow all of the following criteria BEFORE opening a Pull Request:

• Source Branch is up to date with the latest Destination Branch.
• Branch builds cleanly.
• Branch does not contain linter errors.
• Any extraneous debugging code is removed.

You can then add your appropriate reviewers. This should include your lead developer and other team members affected by the change.

We recommend including the Jira ticket number in your PR Title to keep things organized.

4. Address Review Feedback

After your colleagues review the code changes, they should share questions, concerns, and/or suggested improvements. The PR Requestor is responsible for addressing this feedback promptly.

There may be multiple passes back and forth during the review process. After PR comments are addressed, there will be another review, which could generate additional feedback. Don’t move on to the next step until everyone feels comfortable with the final code changes.

5. Merge the Pull Request

Once you have sufficient approval, the Jira ticket should be re-assigned to the original developer, who will merge the pull request. Check the “Delete `branch-name` after merging” checkbox in Bitbucket (our preferred Git-based code hosting and collaboration tool) unless you have a specific reason to keep the branch.

After merging, the developer is also responsible for ensuring the code change is successfully deployed to the UAT environment. They should do a quick “smoke test” – a cursory look at the front end to ensure the intended changes are present and working. Once the change is deployed and smoke tested, the developer should move the Jira ticket to the Internal QA column and assign the ticket to the project Business Analyst.

Reviewer Responsibilities

Generally speaking, it is the responsibility of the PR Reviewer to act as a gatekeeper for the codebase and ensure that all code being merged passes code quality standards.

PR Review Focus Points

In general, here’s what a PR Reviewer should look for:

1. Anything that will cause build errors
2. Security risks
3. Duplicate code that should be abstracted/normalized
4. Hard-coded values or secrets
5. Debugging code that should be removed

Out of Scope for PR Review

We have defined a few areas that tend to bleed into PR Review in many businesses, but we intentionally keep out of our process:

1. Personal code style preferences. PR Review is not designed to impose personal code style choices or naming conventions. If the code passes linting (automated source code review for programmatic and stylistic errors), it’s not worth holding up a merge for efficiency.
2. Business Requirements. It is the project’s Business Analyst’s responsibility to ensure that the ticket passes Acceptance Criteria (AC). The PR Reviewer does not need to fully test the UI functionality to approve a PR. If you see functionality that is clearly not in line with the AC, we encourage our team members to call it out. However, for the most part, we ask our developers to leave the business requirements testing for the BA for efficiency.

Matching Review Needs to Project Size

Since the scale, requirements, and budget of our projects are variable, there will be different levels of code review needed from project to project. Some large-scale projects will require multiple reviewers on a PR and a higher level of scrutiny. A smaller project may not have the resources to support significant development oversight.

At Soliant, our default rule dictates that any code being merged into a client codebase is reviewed by another developer. Sometimes, there will projects with only a single developer. In these situations, it is best to still have a mechanism in place that allows another developer to review code changes. It may not be feasible to have a code review on every task. However, at the very least, we have another developer review batches of tickets before they are deployed to a production environment.

Leveraging Junior Developers

We find that training junior developers by instructing them to make daily commits to update a Work In Progress (WIP) branch helps them learn quickly. This strategy also allows the lead developer to incrementally review code to measure progress and to catch any mistakes early on. Just make sure that all of the Pull Request titles include a [WIP] tag at the start and that any WIP commits are squashed before the branch is merged.

Squashing Commits

Exercise caution when squashing commits. It can cause big issues with git if a sub-branch is made off your branch, and then you squash the commit from which that sub-branch originated.

Commenting Best Practices

There are two categories of comments that should be left on a PR:

1. A suggested code change/fix
2. A question about functionality or code design choice

Be clear in your comments whether you are expecting an explanation or a code change. 

Here are some tips to keep in mind when leaving PR comments:

1. Always try to be constructive, not critical.
2. Be explicit with your feedback. Leave your comments in meaningful places in the code, provide links to code examples or resources you refer to, reference classes/variables by name, etc.
3. Provide reasoning. Let the Requestor know why you’re suggesting a change or questioning their choice. This context will help them grow as a developer.

How to Process a Pull Request

Here is our general workflow for how a Reviewer should process a Pull Request:

NOTE: It is also perfectly reasonable to leave comments on a PR with suggestions for improvements and still mark it approved for merge. This strategy is useful if you have feedback that could help the Requestor in the future but isn’t necessary to change in this PR.

Navigating Disagreements Between the PR Requestor and Reviewer

All projects include some level of discourse, especially as we strive to do our best work for our clients. And our definitions of “correct course of action” can vary as we navigate development projects.

If there is a disagreement between the Requestor and Reviewer, it is encouraged to discuss it and come to a compromise. Or, if necessary, you can bring in another impartial developer to weigh in.

Our goal for the Pull Request review process is to produce high-quality, functional code that meets our high coding standards and is ready to move on to the Quality Assurance stage. It is easy to take Pull Request comments personally, but the process is designed to help improve development skills and deliver the highest quality code possible.

Choosing a Partner with Tested Test Version Control and Pull Management Methods

When working with an external development team to enhance an existing application for your business or create a new one, you put a lot on the line. You need to choose a partner that understands your preferred technology and how to deliver high-quality code regardless of tech stack or ecosystem. Our experienced developers have deep knowledge and expertise in version control systems and pull management practices to ensure efficient and streamlined code development and collaboration for our clients.

We prioritize safeguarding the integrity of our clients’ codebases by strategically managing code changes and minimizing the risk of conflicts, errors, and inconsistencies. Our development process is built on a foundation of best practices but is customized to each project. This ensures the final code aligns with our clients’ growth trajectory, ensuring scalability and adaptability as the application evolves.

Contact our team to discuss your next project with a consultant and senior developer.