A Brief Note on Version Control and Project Organization

Sulley

2022-11-21

随笔

This is a brief note about the e-book Version Control and Project Organization Best Practice Guide present at Unite 2022. In this book, we can learn fundamental concepts of version control and some best practices for organizing a Unity project. If you are new to Unity, or you prepare to set up a larger scale Unity project, this may be what you need.

Foundational concepts

Version control enables you to keep a historical track of your entire project. It facilitates your collaboration with your team through trackable and revertible commits organized in the form of timeline.
Why use version control
- Useful for making experimental changes
- Easy iteration
- Avoid conflict
Centralized vs. distributed version control
- Centralized: repository is resided in a dedicated server, and changes are fetched from and sent to the repository directly. To avoid conflicts, users can lock files for modification, which is known as checking out the file.
- Distributed: users have local copy of the project and submit changes whenever they want without always working on the latest files like on a centralized system. But it costs a lot of space to store the entire history changes.
Typical workflow
- Centralized
  1. Update your working copy with changes from the server
  2. Make your changes
  3. Commit your changes to the central server
- Distributed
  1. Pull any remote changes into your local repo
  2. Make changes
  3. Commit changes
  4. Push changes back to the remote repo

Best practices for organizing a Unity project

Folder structure
- Recommendations:
  - Document your naming conventions and folder structure.
  - Be consistent with your naming convention.
  - Don't use spaces in file and folder names.
  - Separate testing or sandbox areas.
  - Avoid extra folders at the root level.
  - Keep your internal assets from third-party ones.
The .meta file: it holds information about the file which it is associated with, e.g., Textures, meshes, audio clips that have particular import settings.
Naming standards:
- Use descriptive names, not abbreviate.
- Use Camel case/Pascal case.
- Use underscore sparingly.
- Use number suffixes to denote a sequence.
- Follow document naming.
Workflow optimization:
- Split up your assets: break levels into smaller scenes, using SceneManager.LoadSceneAsync; break work up into Prefabs where possible.
- Use Preset to save asset settings.

Code standards

Decide a code standard and stick with it.
When using namespace, break your folder structure up by the namespace for better organization.
Using a standard header.
Using script templates by creating an Assets/ScriptTemplates folder.

You can also use your own keywords and replace them with an Editor script implementing the OnWillCreateAsset method.

// /*-------------------------------------------
// ---------------------------------------------
// Creation Date: #DATETIME#
// Author: #DEVELOPER#
// Description: #PROJECTNAME#
// ---------------------------------------------
// -------------------------------------------*/
using UnityEngine;
using UnityEditor;
public class KeywordReplace : UnityEditor .AssetModificationProcessor {

    public static void OnWillCreateAsset (string path)
    {
        path = path.Replace(".meta", "");
        int index = path.LastIndexOf(".");
        if (index < 0)
            return;

        string file = path.Substring(index);
        if (file != ".cs" && file != ".js" && file != ".boo")
            return;

        index = Application.dataPath.LastIndexOf("Assets");
        path = Application.dataPath.Substring(0, index) + path;
        if (!System.IO.File.Exists(path))
            return;

        string fileContent = System.IO.File.ReadAllText(path);

        fileContent = fileContent.Replace("#CREATIONDATE#", System.DateTime.Today.ToString("dd/MM/yy") + "");
        fileContent = fileContent.Replace("#PROJECTNAME#", PlayerSettings.product-Name);
        fileContent = fileContent.Replace("#DEVELOPER#", System.Environment.User-Name);

        System.IO.File.WriteAllText(path, fileContent);
        AssetDatabase.Refresh();
    }
}

Version control systems

Git: Fork, GitKraken, VS Code, VS, SourceTree, Sublime Merge.
Perforce (Helix Core): see here to learn how to integrate Perforce into Unity.
Apache Subversion (SVN)
Plastic SCM: see here to learn more about Plastic SCM.

Settings up Unity to work with version control

Editor project settings
- Perforce: Edit -> Project Settings -> Version Control -> Mode.
- Plastic SCM: click the Plastic SCM icon in the toolbar on the top right in Unity Editor.
What to ignore: Do not commit the Library folder, as well as the .exe or .apk files.
Work with large files: teams prefer a centralized workflow where large binary files would only on a central server with individual users only accessing the latest version on their machines, rather than a distributed one where many copies of historical files are stored on local machines. If using Git, be sure to include Git LFS.

Best practices for version control

Some suggestions you may need to make teamwork more efficient:

Commit little, commit often.
Keep commit messages clean.
Avoid indiscriminate commits. It is important to understand that you should only commit what you have changed in the project.
Get the latest
- Git: pull -> edit -> pull -> commit -> pull -> push.
- Perforce: get latest -> check out files -> edit -> submit
Know your toolset
- Git: UI client
- Plastic SCM: Gluon
- Perforce Helix Core: built-in Unity Editor tools
Feature branches and Git Flow: main, hotfix, release, develop, etc. Both Plastic SCM and Perforce have automated tools to help manage merging branches back into mainline. Plastic SCM does this with the help of MergeBot, and Perforce uses Helix Swarm for managing code reviews that can also be set up with automated testing.

The biggest takeaway is the importance of clear team communication. As a team, you need to agree on your guidelines