Best practices for version control

This is by far the simplest improvement you can make to your workflow, yet it’s the one that some developers struggle with the most. When working with other project management tools, it’s likely that you’ve already broken down the work into small, manageable tasks. Commits should be treated the exact same way.

A single commit should only relate to one task or ticket, unless a single line of code magically fixes several bugs. If you are working on a larger feature, break it down into smaller tasks, and make commits for each.

The greatest advantage of using smaller commits is that, if something does go wrong, you can detect and revert undesirable changes much more easily.

Commit messages describe the history of your project. After all, it’s much easier to find the change that added high-score tables to your game if its commit message reads “added high-score tables to the menu” rather than “bet you can’t beat my score on these new tables!”

When working with a task ticketing system like Jira or GitLab, it’s even better to include a ticket number in your commit. Many systems can be set up to work together with smart commits so that you can actually reference tickets and change their status from your commit message.

For example, a commit that reads “JRA-123 #close #comment task completed” would set the Jira ticket JRA-123 to closed, leaving the comment “task completed” on the ticket.

For more on setting up this workflow, see the documentation in Jira or the Pivotal Tracker service in GitLab.

The only time “commit -a” (the Git command for “commit all changes”) or any of its counterparts should be used is with the first commit of a project. Usually, this is when the only files in the project are README.md.

A commit should only include files that are related to the change you are committing to the repo. You should be particularly careful when working with Unity projects because some changes can result in several files being marked as changed, such as scenes, Prefabs, or Sprite Atlases, even though you didn’t intend to make any changes to them.

If you accidentally commit a change to a scene that someone else is working on, for example, this can cause a headache for them when they go to commit their changes and see that they need to merge your changes first.

This is one of the most common mistakes that people who are new to version control will make. It’s important to understand that you should only commit your own changes to the project. To learn more, check out this blog post on how to speed up your workflow.

As often as it makes sense, pull the latest changes from the repo into your working copy. It’s not a good idea to work off in isolation, as this only increases the likelihood of merge conflicts. See the table above to get an idea of a typical daily workflow for each system.

Plastic SCM workflows are a little different because you can work in centralized, distributed, or multisite configurations.

Multisite configurations can be fairly unique, with each user working in either a centralized or distributed workflow.

Consider the following example:

• Two teams
• Each team has an onsite server
• Team members check in locally or distributed at each site, but benefit from the speed of a close onsite server
• Servers push and pull between one another to stay fully or partially in sync

Regardless of the VCS your team chooses to work with, make sure that everyone is comfortable using it and understands the tools at their disposal.

If you’re working with Git, not everyone needs to use the same GUI client. But make it a priority to see that everyone feels comfortable with the commit > pull > push workflow. In other words, they should have the knowledge to commit only the files they need.

If you’re working with Plastic SCM, encourage the artists on your team to get used to Gluon, a user-friendly GUI to simplify their workflow. Gluon lets you decide on the files you want to work on, removing the need to download and manage the entire project. It also enables you to lock files, which prevents others from working on them. Once you’re finished, submit the files back to the repository and unlock them again as needed.

When working on a long-standing project with multiple release cycles, feature branching is highly beneficial to your workflow. Often, teams work out of the same branch of a repo, likely called trunk, master,or main.

When you do this, your entire project moves along the same timeline. However, it can be useful to split the work off into several branches to collaborate more effectively as a team.

In Git, a specific workflow called Git Flow focuses on using different branches for features, bug fixes, and releases.

So if a developer starts working on a new feature inside of an isolated branch, it will merge back into the main branch once they’re finished. Meanwhile, another teammate can do a hotfix on the previous release, or fix a bug, and release a new version safely, without including any of the features still under development.

Plastic SCM also features task branches. For this pattern, you create a new branch for every task that you track. While in Git Flow, we use feature branches to develop complete, sometimes large, features. Task branches in Plastic SCM are meant to be short-lived. If a task takes more than a handful of commits to implement, odds are that it can be broken down into smaller tasks.

Perforce Helix Core uses a system called Streams to facilitate this style of workflow. When creating a depot to work in, you need to set it up as a stream depot type. Then, you can use the Stream Graph view to create new streams. Every stream (other than the mainline stream) will need to have a parent stream, so that changes can be copied back upstream.

There are different types of streams for different purposes. When you switch between streams on your local workstation or copy changes back upstream, only the metadata for changed files gets merged, making the context change quicker.

Once you’ve completed work on a feature branch, it’s good practice to use pull requests to get your changes back into the main stream of the repo. Pull requests are created by the developers of the feature or task. It’s usually the responsibility of a senior developer or DevOps to review the changes before accepting them into the mainline.

Plastic SCM and Perforce both have automated tools to help manage merging branches back into the mainline. Plastic SCM does this with the help of Mergebot, which automatically merges branches of a repo once they’ve been reviewed and have passed validation. Perforce has an additional platform, Helix Swarm, used for managing code reviews that can also be set up with automated testing.

Even if you’re working on a solo project, the principles of organization and version control can be really useful.

When working with a team, it’s crucial to prioritize clear communication. As a group, you need to agree on your guidelines: how you should structure your project, which version control system to use, and what your workflow in that system should look like.

This way, when you start integrating other tools like Jira, GitLab, build tools, or automated testing, the work you’ve already done structuring your project and workflow will come into its own.