Release Notes

All platforms: Introducing Smart Locks

There are many kinds of files that present a challenge for merging content changes:

* Unity scenes

* 3D models

* Images and texture maps

* Sound files

* Excel spreadsheets

* Etc...

It is quite easy to see how important it is to apply changes to these assets sequentially and always iterate over their last revision. The creation of parallel histories usually means that some changes are discarded and redone down the line, since conflicts in these files cannot be merged.

So far, you could set up these lock rules to guarantee that nobody else made changes to the same file at the same time. When you were done, changes were checked in — or unchecked out — and the lock was removed. This "legacy" lock system was devised mainly for artists that work on a single branch, forcing the user to work on the last revision of the branch.

However, protection did not extend to multi-branch scenarios, allowing the creation of parallel changes in different branches:

1. Alice made some changes to player_icon.jpg at /main/level_12. The scene is waiting to be integrated, and the file is not locked anymore.

2. Bob is working on its own branch (/main/level_11) and makes a quick change to the same file too.

Yes, both are using the last revision on their branch, but they don't take into account new revisions in other branches.

Now introducing Smart Locks.

Smart Locks are the mechanism that Unity DevOps Version Control uses to track which branch retains an asset for edition, and it works as a baton pass or as a "torch". Even if the file is not exclusively checked out right now, task branches retain the lock and prevent developers from checking out an outdated revision in a different branch.

Moreover, locks are not retained by the users who created them. As long as they keep working with the last revision, other developers can still exclusively check out the file you just checked in! This is true even for multi-branch scenarios.

In other words, Smart Locks ensure a single line of development for assets among different branches while enabling collaboration between developers. Long gone are the days when you needed to keep a physical token on your desk to let your colleagues know that you were holding an asset: Unity DevOps Version Control keeps you covered.

== CREATING SMART LOCKS ==

Smart Locks are here to replace legacy locks, and the new version of the server already uses them from the get go (see details in the 'COMPATIBILITY' section). If you were already using locks, you probably just need to upgrade.

First of all, you need to set up the lock rules (if you don't already have them!):

# Contents of the lock.conf file.

rep: * br:/main
*.UNITY
*.dae
*.mkv

rep: myrepo br:/main excluded_branches: /main/experiment /main/experiments/* */art-concept */art-concepts-*
*.jpg
*.png
*.wav

Note that there are two new optional fields available in the lock rules:

1. The "destination branch" — br:/main by default — is the source of truth when creating a new lock: the revision loaded here is considered the last revision. Locks created in other branches are not released until they get integrated back into the destination branch.

2. Some "excluded branches" where the lock rules are ignored. Note that you can use wildcards at the beginning and at the end. Excluded branches are matched by name, so bear it in mind when renaming branches!

After setting up the rules, you can create a task branch and try to check out a file. The "lock list" subcommand will help you to inspect which locks are in place and their current status:

> cm co fmv_intro.mkv

> cm lock list --anystatus
myrepo  1932  6/27/2023 10:02:11 AM /main  241  /main/task 241  Locked  mikel  mywk  /assets/fmv_intro.mkv

# Do some changes and check them in!
> cm ci

> cm lock list --anystatus
myrepo  1932  6/27/2023 10:02:54 AM /main  241  /main/task 242  Retained  mikel  mywk  /assets/fmv_intro.mkv

# cm lock list --help

Within the Desktop GUI, the Workspace Explorer now tells explicitly which files are locked by other users, and they are represented with special icons for clarity.

Also, a new panel was added to the Desktop GUI and Gluon to display the Smart Locks that currently exist in the workspace repository. Since there, you can release or remove the locks too:

Moreover, this panel is available in both, the Workspace Explorer and the Home View, so you don't even need a workspace to manage the locks of a repository.

Likewise, the same functionality is provided by the WebUI:

Remark: note legacy locks as they are not truly tied to specific repositories, so they cannot be visualized this way. Running "lock list --anystatus" shows all the server locks by default, so you can use it to find them if necessary.

See in detail how to configure exclusive check-out using an on-prem server in our administrator guide:

https://docs.plasticscm.com/administration/plastic-scm-version-control-administrator-guide#Chapter7:Configuringexclusivecheckout(Lock)

== LIMITATIONS ==

* Smart Locks do not travel across replicas.

* Replicas might add newer revisions to the repository, leaving the lock outdated.

* Some scenarios involving changeset deletion might leave the lock outdated for obvious reasons.

* Merge-to does not support locks — neither legacy nor smart ones —... yet! Stay tuned.

Even if you bump into such scenarios, none of them are unrecoverable. See the following section.

== REMOVING AND RECREATING LOCKS ==

You might land in a situation where a lock must be forcefully unlocked — maybe somebody locked an asset and forgot to release it, or maybe a lock was invalidated for some other reason.

You can use the Desktop GUI, Gluon, or the WebUI to release or remove the lock. Alternatively, you can also use the "lock unlock" subcommand:

# Unlocks the lock for the item id 56 in the repo 'myrep@myorg@cloud'.
> cm lock unlock itemid:56@myrep@myorg@cloud

# Unlocks the lock of an item by path.
> cm lock unlock /home/user/workspace/foo.psd

# Not just unlock the item, remove it entirely.
> cm lock unlock foo.psd --remove

# cm lock unlock --help

By the way, if you really need to remove a lock entirely, you might want to recreate it somewhere else. You can use the "lock create" subcommand for that. Lock rules already determine which is the destination branch, but you still need to explicitly specify the holder branch, like so:

# Creates a lock for the item id 56 in the branch /main/task@myrep.
> cm lock create /main/task@myrep itemid:56@myrep

# Creates a lock for the selected item in the branch /main/task.
> cm lock create br:/main/task item:/home/user/workspace/foo.psd

# cm lock create --help

== COMPATIBILITY ==

* Before, lock rules allowed a lockserver field (although this was barely used and could introduce some issues). It won't be supported anymore.

* Old versions of the client can perform exclusive check outs over files, but they won't be able to release Smart Locks, only legacy ones. If you try, you will be prompted to upgrade in order to continue.

* After upgrading, legacy locks already in place will stay as they are. But as soon as files get checked in or unchecked out, the legacy lock will be gone. The next time you check out such files, they will start using the new system.

* There could already be parallel versions of some files (coming from legacy locks, if they were used this way). In this case, some manual operations could be needed to continue working with these files during this transition to Smart Locks. 'cm lock unlock' and 'cm lock create' are here to help.

* Legacy locks will still be supported, at least for a while. Indeed, you can disable the new behavior in the server by adding the following key to the server.conf:

<EnableSmartLocks>false</EnableSmartLocks>

You can find more information in the official documentation:

https://docs.unity.com/devops/en/manual/smart-locks

Command-line client: cm update now has its own update report

The update command usually does not show an update report. Instead, it shows a progress bar (if used interactively) or all the relevant events that happen on items as they are updated (a behavior intended for tool automation).

However, the progress bar does not clearly communicate errors. Now using cm update interactively features an update report at the end, which helps to better understand what happened:

> cm update
| Finished       [####################] 100%  510/510 MB - 204/204 file
Error updating 'c:\wks\Game\Source\main.cs': (...)
Warning updating 'c:\wks\Game\Source\Utils.cs': (...)
>