-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #242 from ynput/ayon-version-control-drafts
Add Ayon version control addon docs
- Loading branch information
Showing
13 changed files
with
325 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,91 @@ | ||
--- | ||
id: addon_version_control_admin_get_started | ||
title: Version Control Get Started | ||
sidebar_label: Get Started | ||
description: Version Control Get Started. | ||
toc_max_heading_level: 5 | ||
--- | ||
|
||
import ReactMarkdown from "react-markdown"; | ||
import versions from '@site/docs/assets/json/Ayon_addons_version.json' | ||
|
||
<ReactMarkdown> | ||
{versions.VersionControl_Badge} | ||
</ReactMarkdown> | ||
|
||
## Current state of the addon | ||
|
||
This addon tries to implement generic API for various version control system. | ||
|
||
Currently contains WIP implementation of Perforce, but there might be more in the future which should follow | ||
same API methods. | ||
|
||
The implementation aims to rely solely on a single dependency, `p4python`, which is binary-dependent on the Python version in use. | ||
This means it might be different in different DCCs, different versions of Unreal etc. | ||
|
||
To mitigate need of having binary compatible `p4python` libraries addon currently implements REST api to run p4 commands | ||
only on separate webserver started by AYON Tray which contains `p4python` library installed via dependency package and | ||
REST stub class which might be used in each DCC that has `requests` library. | ||
|
||
:::info | ||
The AYON Version Control addon doesn't replace the built-in versioning functionality. | ||
Instead, it adds an extra layer by publishing the product to two separate locations: the AYON publish directory and the Perforce server. | ||
::: | ||
|
||
## Configuration of connection to Perforce server | ||
|
||
Addons offers configuration of credentials to P4 server with username and password on multiple levels via | ||
Studio(single credentials), Project (credentials different per project) or Site settings(credentials different per artist.) | ||
|
||
## Perforce workspace | ||
|
||
It is expected that P4 workspaces would be setup and existed on artists machines. Each artist then only | ||
provides path to their locally accessible P4 workspace folder in Site Settings. | ||
|
||
## Main functionalities for Perforce | ||
|
||
This addons contains two main functionalities for slightly different use cases: | ||
- create separate version controlled streams from AYON of published products in Perforce | ||
- help with Deadline rendering of Unreal projects with Perforce | ||
|
||
It is expected that majority working for Perforce with Unreal project files are done with official Perforce | ||
tools like `P4V` or command line utility. Neither of those are distributed by addon and it is required | ||
for IT department to install/configure them. | ||
|
||
|
||
### Commits to Perforce | ||
|
||
This approach allows to copy version control not only in AYON, where each publish results in new version | ||
of published product, but committing this version directly to Perforce. | ||
|
||
The products with versions are separately kept in Perforce, from which ordinary Perforce tools | ||
could be used (P4V) to pull latest version of published product. | ||
|
||
Profiles could be used to limit which published products should be committed to Perforce. | ||
|
||
As Perforce controls the product which doesn't contain version name directly in its name nor path, additional | ||
AYON template must be configured in Project's Anatomy > Templates. | ||
|
||
New template must follow [Hero template](artist_concepts.md#hero-version) approach, | ||
`Hero` template could be used directly too (if it is matching required folder structure in Perforce) | ||
|
||
### Support for Unreal and Deadline | ||
|
||
The other workflow is to help rendering Unreal from Perforce on Deadline rendering farm. | ||
|
||
In this use case there is an exception that multiple artists are working on Unreal project with standard utilization of | ||
P4 or Unreal P4 official plugin to checkout/commit any modifications to Unreal project to Perforce. | ||
|
||
Addons offers additional possibility to mark current stage of Unreal project, eg. latest commit/changelist, as 'published' and | ||
store its metadata in AYON for possible future workflows and enhancements. | ||
|
||
New additional mini tool is provided for artists before they open Unreal via AYON launcher which allows them to | ||
`P4 sync` (not `checkout` - that would lock the files) to any previously published version before Unreal is actually opened. | ||
|
||
This marker, or tag, points to commit/changelist and could be pushed to Deadline integration where Deadline | ||
syncs to this particular commit before rendering. | ||
|
||
This requires to have AYON integration to Deadline installed. Please check https://ayon.ynput.io/docs/addon_deadline_admin for more details. | ||
|
||
Usage of Perforce in Deadline submissions could be controlled by toggling on/off of automatically created instance of | ||
`changelist_metadata` product type in AYON Publisher. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,76 @@ | ||
--- | ||
id: addon_version_control_admin_intro | ||
title: Version Control Intro | ||
sidebar_label: Intro | ||
description: Version Control Intro. | ||
toc_max_heading_level: 5 | ||
--- | ||
|
||
import Tabs from '@theme/Tabs'; | ||
import TabItem from '@theme/TabItem'; | ||
|
||
## What is version control ? | ||
|
||
Version control, as defined by [Git](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control), is a system that records changes to a file or set of files over time. This allows you to revisit and restore earlier versions if needed. | ||
|
||
Now, you might wonder, doesn't AYON do something similar? We'll dive deeper into this in the following section. | ||
|
||
## Nature of Version Control | ||
:::tip | ||
Version control, conceptually, is similar to hero versioning where you have a master version that points to one preferred version among other saved versions. | ||
::: | ||
|
||
AYON at its core adopts the traditional up-versioning strategy, which stands apart from using a Version Control System. But what sets them apart? Let's compare the two to highlight key differences: | ||
|
||
<Tabs | ||
groupId="vc_vs_up_versioning" | ||
defaultValue="upversioning" | ||
values={[ | ||
{label: 'Up-Versioning', value: 'upversioning'}, | ||
{label: 'Version-Control', value: 'versioncontrol'}, | ||
]}> | ||
|
||
<TabItem value="upversioning"> | ||
|
||
- Uses a folder-based structure. | ||
- Updates are made by creating a new folder labeled with the next version number and saving the updated files there. | ||
- To access a specific version, you simply navigate to the folder labeled with that version number. | ||
- Allows simultaneous access to multiple versions, like loading v005, v008, and v009 simultaneously. | ||
- Reviewing the history requires going through the folder structure. | ||
|
||
</TabItem> | ||
|
||
<TabItem value="versioncontrol"> | ||
|
||
- Uses a repository, Think of a repository as a database that keeps track of all version histories. | ||
- Updates are made by committing changes, which are essentially snapshots of your files at a specific point in time. | ||
- Accessing a specific version involves using commands to revert your files to that particular snapshot. | ||
- Although it requires extra effort, it's possible to access multiple versions at once, like loading v005, v008, and v009 simultaneously. | ||
- Reviewing the history requires using a dedicated tool designed for tracking and visualizing version histories. | ||
|
||
</TabItem> | ||
|
||
</Tabs> | ||
|
||
:::tip | ||
From a pipeline perspective, users can remain focused on their tasks without worrying about the inner workings of various systems in the backend, as these are fully managed by the pipeline. | ||
|
||
Additionally, it is up to the pipeline admin to choose the most suitable version control system. | ||
::: | ||
|
||
## Version Control & Creative Industries | ||
|
||
Version control is widely recognized in the gaming industry and virtual production, more so than in other creative sectors such as VFX, animation and advertising. | ||
This is reflected in the extensive discussions on forums and official sites for Unreal Engine or Unity. | ||
|
||
For instance, Epic Games offers an insightful article [Versioning and Source Control](https://dev.epicgames.com/community/learning/tutorials/jO2m/unreal-engine-versioning-and-source-control), which delves into: | ||
- Comprehensive tutorials on version control basics. | ||
- Workflow practices for version control in virtual production. | ||
- Building an Asset Library in Perforce, catering to various projects, sequences, seasons, episodes, and more. | ||
|
||
## Learn More | ||
|
||
- [What is Git?](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F) | ||
- [Perforce Helix Core vs Git](https://get.assembla.com/blog/perforce-vs-git/) | ||
- [Perforce Helix Core Beginner’s Guide](https://www.youtube.com/playlist?list=PLH3pq2J85xsPYn71_yzzsZQKvalTW-duE) | ||
- [Perforce Helix Core Admin’s Guide](https://www.youtube.com/playlist?list=PLH3pq2J85xsMDY2AAkzUhTmHIg1S7WN1f) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
--- | ||
id: addon_version_control_admin_settings | ||
title: Version Control Addon Settings | ||
sidebar_label: Version Control Settings | ||
description: Version Control Addon Settings. | ||
toc_max_heading_level: 5 | ||
--- | ||
|
||
import ReactMarkdown from "react-markdown"; | ||
import versions from '@site/docs/assets/json/Ayon_addons_version.json' | ||
|
||
<ReactMarkdown> | ||
{versions.VersionControl_Badge} | ||
</ReactMarkdown> | ||
|
||
## Addon Settings | ||
![](assets/version_control/connection_settings.png) | ||
|
||
- **Backend name:** List of active version control systems. | ||
- **Host name:** Pipeline integration name for the backend name. | ||
- **Port:** port number that perforce server uses. | ||
:::info | ||
By default, The server url for perforce is expected to be `http://localhost:{Port}`. | ||
Keep in mind that the addon sets the URL to `PERFORCE_WEBSERVER_URL` environment variable. | ||
::: | ||
|
||
## Publish Plugins | ||
|
||
### Collect Version Control | ||
|
||
![](assets/version_control/collect_version_control.png) | ||
|
||
**Profiles:** | ||
- Host names | ||
- Families | ||
- Task Types | ||
- Task names | ||
- Add Version Control to representations | ||
- **Template name:** Name from Anatomy to provide path and name of committed file. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,78 @@ | ||
--- | ||
id: addon_version_control_artist | ||
title: Version Control Artist Docs | ||
sidebar_label: Version Control | ||
description: Version Control Addon's documentations for artists. | ||
toc_max_heading_level: 5 | ||
--- | ||
|
||
:::tip | ||
Currently, the addon implements basic Perforce support inside of Unreal. | ||
::: | ||
|
||
## Get Started | ||
|
||
### User Setup | ||
|
||
:::info Perforce Workspace | ||
It is expected that P4 workspaces would be setup and existed on artists machines. | ||
::: | ||
|
||
![](assets/version_control/site_settings_user_credentials.png) | ||
|
||
Perforce site settings user name, password and workspace directory. | ||
|
||
### Launch Unreal with version control enabled | ||
|
||
When starting Unreal via AYON Launcher, a pop window will show up before Unreal launch allows you to sync to specific a change list. | ||
![](assets/version_control/perforce_changes_viewer.png) | ||
|
||
## How Perforce support works | ||
|
||
:::tip | ||
We assume that you always on the latest change list. | ||
::: | ||
|
||
## Workflows | ||
|
||
Perforce doesn't replace regular AYON publishing. | ||
Because commit changes to perforce and publish to AYON are two separate actions. | ||
And, you can do both for the same asset! | ||
|
||
So for example, you can use AYON to publish assets and use perforce to setup and version control your scene. | ||
|
||
|
||
### Commit Strategy | ||
|
||
| Unreal | Visible in AYON | | ||
|--|--| | ||
| commit | | | ||
| commit | | | ||
| Publish to AYON | ✅ | | ||
| commit | | | ||
| Publish to AYON | ✅ | | ||
|
||
### `Publish to AYON` Process | ||
|
||
When having any workfile changes while workfile instance is enabled, AYON will commit them automatically before publishing. | ||
|
||
Publish `change list` info as Json file. | ||
Publish your files to AYON. | ||
if you are publishing the same asset that you are pushing to perforce, then AYON publish will be more like taking a snapshot of that asset at a particular `change list` and save it like any other published assets. which makes it available for other DCCs as well. | ||
|
||
|
||
### Deadline | ||
|
||
:::info | ||
Current Deadline implementation requires P4 depots to be of type 'stream' and workspace to be assigned to a stream. | ||
::: | ||
|
||
When having any workfile changes while workfile instance is enabled, AYON will commit them automatically before sending the deadline job. | ||
|
||
<!-- TODO: Answer the following questions | ||
## FAQ | ||
### Do the addon support submitting a deadline job with a specific change list number? | ||
### What happens when I submit a render, pause it, do some commits in perforce and requeue the render job? --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+29.6 KB
website/docs/assets/version_control/site_settings_user_credentials.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
import { type Addon } from "../types"; | ||
import versions from "@site/docs/assets/json/Ayon_addons_version.json"; | ||
|
||
const addon: Addon = { | ||
title: "Version Control", | ||
description: | ||
"The AYON Version Control addon implements a generic API that can be used with various version control systems, with a primary focus on Perforce.", | ||
icon: "perforce-icon.png", | ||
badge: versions.VersionControl_Badge, | ||
features: [ | ||
], | ||
products: [ | ||
], | ||
docs: { | ||
user: "addon_version_control_artist", | ||
admin: "category/version-control", | ||
}, | ||
github: "https://github.com/ynput/ayon-version-control", | ||
}; | ||
|
||
export default addon; |