diff --git a/website/docs/addon_version_control_admin_get_started.md b/website/docs/addon_version_control_admin_get_started.md new file mode 100644 index 00000000..2bab526a --- /dev/null +++ b/website/docs/addon_version_control_admin_get_started.md @@ -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' + + + {versions.VersionControl_Badge} + + +## 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. diff --git a/website/docs/addon_version_control_admin_intro.md b/website/docs/addon_version_control_admin_intro.md new file mode 100644 index 00000000..3b7947bb --- /dev/null +++ b/website/docs/addon_version_control_admin_intro.md @@ -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: + + + + + +- 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. + + + + + +- 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. + + + + + +:::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) diff --git a/website/docs/addon_version_control_admin_settings.md b/website/docs/addon_version_control_admin_settings.md new file mode 100644 index 00000000..f93b4275 --- /dev/null +++ b/website/docs/addon_version_control_admin_settings.md @@ -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' + + + {versions.VersionControl_Badge} + + +## 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. + diff --git a/website/docs/addon_version_control_artist.md b/website/docs/addon_version_control_artist.md new file mode 100644 index 00000000..9f5adaa6 --- /dev/null +++ b/website/docs/addon_version_control_artist.md @@ -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. + + diff --git a/website/docs/assets/json/Ayon_addons_version.json b/website/docs/assets/json/Ayon_addons_version.json index 9ac696d9..ca27ca4d 100644 --- a/website/docs/assets/json/Ayon_addons_version.json +++ b/website/docs/assets/json/Ayon_addons_version.json @@ -38,6 +38,7 @@ "USD_Badge" : "[![USD Addon - 0.1.2](https://img.shields.io/badge/USD_Addon-1.0.3-1c91d4)](https://github.com/ynput/ayon-usd)", "Wrap_Badge" : "![wrap - 0.0.1](https://img.shields.io/badge/wrap-0.0.1-2f4249)", "Zbrush_Badge" : "![zbrush - 0.1.0](https://img.shields.io/badge/zbrush-0.1.0-2f4249)", + "VersionControl_Badge" : "[![Version Control - 0.0.2](https://img.shields.io/badge/Version_Control-0.0.2-404040?logo=perforce)](https://github.com/ynput/ayon-version-control)", "Teamplate_Badge" : "[![Template Badge - #.#.#](https://img.shields.io/badge/Template_Badge-%23.%23.%23-00d6a1)](https://github.com/ynput/OpenPype/tree/develop/openpype/modules/example_addons)" } \ No newline at end of file diff --git a/website/docs/assets/version_control/collect_version_control.png b/website/docs/assets/version_control/collect_version_control.png new file mode 100644 index 00000000..d07cc58b Binary files /dev/null and b/website/docs/assets/version_control/collect_version_control.png differ diff --git a/website/docs/assets/version_control/connection_settings.png b/website/docs/assets/version_control/connection_settings.png new file mode 100644 index 00000000..8a418297 Binary files /dev/null and b/website/docs/assets/version_control/connection_settings.png differ diff --git a/website/docs/assets/version_control/perforce_changes_viewer.png b/website/docs/assets/version_control/perforce_changes_viewer.png new file mode 100644 index 00000000..389650fd Binary files /dev/null and b/website/docs/assets/version_control/perforce_changes_viewer.png differ diff --git a/website/docs/assets/version_control/site_settings_user_credentials.png b/website/docs/assets/version_control/site_settings_user_credentials.png new file mode 100644 index 00000000..c440e1b7 Binary files /dev/null and b/website/docs/assets/version_control/site_settings_user_credentials.png differ diff --git a/website/sidebars.js b/website/sidebars.js index 4e1be349..26aaa5d5 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -93,6 +93,7 @@ module.exports = { "addon_substancepainter_artist", "addon_tvpaint_artist", "addon_unreal_artist", + "addon_version_control_artist", "addon_wrap_artist", "addon_openrv_artist", { @@ -201,6 +202,22 @@ module.exports = { }, "addon_aquarium_admin", "addon_usd_admin", + { + type: "category", + label: "Version Control", + link: { + type: 'generated-index', + title: 'AYON Version Control', + description: + "Welcome to AYON Version Control Docs!", + keywords: ['version-control'], + }, + items: [ + "addon_version_control_admin_intro", + "addon_version_control_admin_get_started", + "addon_version_control_admin_settings" + ] + }, ].sort(sorted), }, "admin_releases", diff --git a/website/src/data/addons/addons.ts b/website/src/data/addons/addons.ts index dd4343b5..8a526a01 100644 --- a/website/src/data/addons/addons.ts +++ b/website/src/data/addons/addons.ts @@ -48,6 +48,7 @@ export const officialAddons = [ "slack", "tvpaint", "unreal", + "versioncontrol", "wrap", "openrv", "openusd", diff --git a/website/src/data/addons/data/img/perforce-icon.png b/website/src/data/addons/data/img/perforce-icon.png new file mode 100644 index 00000000..cf40dcee Binary files /dev/null and b/website/src/data/addons/data/img/perforce-icon.png differ diff --git a/website/src/data/addons/data/versioncontrol.ts b/website/src/data/addons/data/versioncontrol.ts new file mode 100644 index 00000000..ad39c2c9 --- /dev/null +++ b/website/src/data/addons/data/versioncontrol.ts @@ -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;