Merge pull request #242 from ynput/ayon-version-control-drafts

Add Ayon version control addon docs

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'
+
+<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.

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:
+
+<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)

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'
+
+<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.
+

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.
+
+<!-- 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? -->

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)"
 }

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",

website/src/data/addons/addons.ts

@@ -48,6 +48,7 @@ export const officialAddons = [
     "slack",
     "tvpaint",
     "unreal",
+    "versioncontrol",
     "wrap",
     "openrv",
     "openusd",

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;