New article: Merge Conflicts on Flexible Environments

umbraco-cloud/SUMMARY.md

@@ -131,6 +131,7 @@
   * [Extraction error: Config transforms failing](troubleshooting/deployments/changes-not-being-applied.md)
   * [Extraction error: Data Type collisions](troubleshooting/deployments/colliding-datatypes.md)
   * [Dependency Exception](troubleshooting/deployments/dependency-exceptions.md)
+  * [Merge Conflicts on Flexible Environments](troubleshooting/deployments/merge-conflicts-on-flexible-environments.md)
   * [Troubleshooting deployments failing with no error message](troubleshooting/deployments/deployment-failed.md)
   * [Troubleshooting duplicate dictionary items](troubleshooting/deployments/duplicate-dictionary-items.md)
   * [Troubleshooting language mismatches](troubleshooting/deployments/language-mismatch.md)

umbraco-cloud/deployment/restoring-content/README.md

@@ -1,10 +1,10 @@
 # Restoring Content
 
-When you have content on your Cloud environment and you clone down your Umbraco Cloud project to your local machine, you will need to do an extra step, to see your content locally. You will also need to use the restore option when setting up new Umbraco Cloud environments.
+When you have content on your Cloud environment and clone down your project to your local machine, you need to restore the content. You will also need to use the restore option when setting up new Cloud environments.
 
-The restore option comes in handy when you have content editors creating content on the Live or Staging environments. You will be able to restore and work with that content in your Development and local environments.
+The restore option can be used to always ensure you work with the latest content when delevoping new features.
 
-## Step-by-step
+## How to Restore Content
 
 You can restore the content in the following ways:
 
@@ -21,32 +21,28 @@ The first time you run your project locally you will have the option to restore
 This will restore **all** the content nodes and any media dependencies.
 {% endhint %}
 
-1. When your site is done spinning up, click the green **Restore** button to restore all the content nodes and media files.
-2. Wait till the process completes. This might take a while depending on the amount of content and media you have on your project.
-3. When it's completed, select **Open Umbraco** to go to the Backoffice.
-4. You will now see all your content and media in the Umbraco Backoffice.
+1. Run the website locally.
+2. Click the green **Restore** button to restore all the content nodes and media files.
+3. Wait till the process completes. This might take a while depending on the amount of content and media you have on your project.
+4. Select **Open Umbraco** to go to the Backoffice.
+
+All your content and media is now available in the Umbraco Backoffice.
 
 ![Restore from start-up](images/Normal-Restore.gif)
 
 ### Workspace Restore
 
 Use this option when setting up new Cloud environments. The Workspace restore option restores all the entities (content, media, forms, datasources, and prevalue sources from Umbraco Forms) of a workspace via the Backoffice.
 
-1. Log in to the Umbraco Backoffice in the environment you want to restore the content and media.
+1. Log in to the Umbraco Backoffice on the environment you want to restore the content and media.
 2. Click **...** and select **Do something else** or Right-click the **Content** Tree in the Content section.
 3. Choose **Workspace Restore**.
 4. Select the environment from the **Restore this workspace from** dropdown.
-5. To ensure the restore succeeds, make sure that your environments have the [same metadata and structure files](../cloud-to-cloud.md).
-6. Click **Restore from \<environment\_name>** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project.
-7. Once the content restore is completed, you will get a notification with a timestamp. Click **Okay** to complete the process.
+5. Make sure that your environments have the [same schema](../cloud-to-cloud.md).
+6. Click **Restore from <environment_name>** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project.
+7. Click **Okay** to complete the process once the restore is done.
 8. Right-click the **Content** tree and choose **Reload** to see your content in the tree.
 
-{% hint style="info" %}
-If any of your content nodes depends on media items, these will also be restored in the process.
-
-To see the media, go to the **Media** section and **reload** the tree.
-{% endhint %}
-
 ![Workspace Restore](images/Workspace\_Restore.gif)
 
 {% embed url="https://www.youtube.com/embed/0jIhKZOSeLc?rel=0" %}
@@ -55,15 +51,15 @@ Workspace restore
 
 ### Tree Restore
 
-The Tree restore option restores all the entities available for the selected tree in that section. It's available in the **Content**, **Media**, **Members**, **Forms** (root node of Forms, Datasources, and Prevalue sources), or **Translation** (Dictionary menu if configured) sections. Using Tree Restore, you can, for example, restore all your content only. This will restore any media that’s referenced in that content, but it won’t attempt to restore the full media library.
+The Tree restore option restores all the entities available for the selected tree in that section. It's available in the **Content**, **Media**, **Members**, **Forms** (root node of Forms, Datasources, and Prevalue sources), or **Translation** (Dictionary menu if configured) sections. Using Tree Restore, you can choose to restore only content. This will restore any media that’s referenced in that content, but it won’t attempt to restore the full media library.
 
 1. Log in to the Umbraco Backoffice in the environment you want to restore the tree.
 2. Click **...** and select **Do something else** or Right-click the **Content** Tree in the Content section.
 3. Choose **Tree Restore**.
 4. Select the environment from the **Restore this tree from** dropdown.
-5. To ensure the restore succeeds, make sure that your environments have the [same metadata and structure files](../cloud-to-cloud.md).
-6. Click **Restore from \<environment\_name>** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project.
-7. Once the content restore is completed, you will get a notification with a timestamp. Click **Okay** to complete the process.
+5. Make sure that your environments have the [same schema](../cloud-to-cloud.md).
+6. Click **Restore from <environment_name>** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project.
+7. Click **Okay** to complete the process when the restore is done.
 8. Right-click the **Content** tree and choose **Reload** to see your content in the tree.
 
 ![Tree Restore](images/Tree-Restore.gif)
@@ -74,4 +70,4 @@ Video example.
 
 ### [Partial Restore](partial-restore.md)
 
-Using the Partial Restore option, you can restore only a single node from a tree (optionally with descendants) that you need to work with.
+Using the Partial Restore option, you can restore single nodes from a tree (optionally with descendants) that you need to work with.

umbraco-cloud/deployment/restoring-content/partial-restore.md

@@ -1,6 +1,6 @@
 # Partial Restores
 
-In some cases, you might not want to restore the entire content tree but only the parts that you need. **Partial restore** is a feature that allows for restoring specific parts of your content instead of restoring everything.
+In some cases, you might not want to restore the entire content tree but only the parts that you need. Partial restore is a feature that allows for restoring specific parts of your content instead of restoring everything.
 
 You can use Partial Restore on:
 
@@ -13,48 +13,42 @@ You can use Partial Restore on:
 This feature is only available with Umbraco Deploy 3.3+
 {% endhint %}
 
-In this scenario, you've cloned down your Cloud environment to your local machine or set up a new Cloud environment. In both cases, the new environment will have an empty Content section as well as an empty Media section.
+In this scenario, the Cloud environment is cloned to your local machine or a new Cloud environment has been created. In both cases, the new environment will have an empty Content section as well as an empty Media section.
 
 {% hint style="info" %}
-This feature will also restore all dependencies of the selected content. For example, when you restore a content node that references media items as well as other content nodes, these will all be restored, including any parent nodes that these nodes depend on.
+This feature will also restore all dependencies of the selected content. When you restore a content node that references media items and other content nodes, these will all be restored. This includes any parent nodes that these nodes depend on.
 {% endhint %}
 
 To partially restore the parts you need:
 
 1. Go to the **Content** section of the Umbraco backoffice on your new environment (local or Cloud).
 2. Right-click the **Content** tree or click the three dots and select **Do something else**.
-3. Choose **Partial Restore**
+3. Choose **Partial Restore**.
 4. Select the environment that you would like to restore the content from.
-5. Click **Select content to restore** and a dialog with a preview of the content tree from the environment you selected opens.
+5. **Select content to restore** to open a dialog with a preview of the content tree.
 6. Select the content node you would like to restore.
-7. Enable **Including all items below** if you want to restore any child nodes _below_ the selected node.
+7. Enable **Including all items below** if you want to restore any child nodes below the selected node.
 8. Click **Restore**.
-9. Once the restore is completed, right-click the Content tree and select **Reload**.
-
-{% hint style="info" %}
-If you select a content node deeper down the tree, all the parents above it, required for the node to exist, will be restored as well.
-{% endhint %}
+9. Right-click the Content tree and select **Reload** once the restore is complete.
 
 ![Partial restore on empty environment](<../../../umbraco-deploy/deployment-workflow/restoring-content/images/partialRestore-onEmpty (1) (1) (1) (1).gif>)
 
-Partial Restores on empty environments are especially helpful when you have a large amount of content and media and do not necessarily need it all for the task you need to do. Instead of having to restore everything which could potentially take a long time, doing a partial restore can be used to shorten the waiting time by only restoring the parts you need. This will ensure that you can quickly get on your way with the task at hand.
+Partial Restores on empty environments are helpful when not all content or media is necessary for the tasks to be performed on the new environment. Instead of having to restore everything, doing a partial restore can be used to only restore the parts you need. This will ensure that you can quickly get on your way with the task at hand.
 
 ## Environment with existing Content or Media
 
-It is also possible to use the Partial Restore feature in environments where you already have content in the Content tree.
-
-Imagine that you are working with your Umbraco Cloud project locally. One of your content editors updates a section in the content tree on the Live environment. You would like to see how this updated content looks with the new code you are working on. To partially restore the updated content node, do the following:
+It is possible to use the Partial Restore feature in environments where you already have content in the Content tree.
 
 1. Go to the **Content** section of your Umbraco backoffice.
 2. Right-click the content node which you know contains updates.
-3. Choose **Partial Restore**
+3. Choose **Partial Restore**.
 4. Select the environment that you would like to restore the content from.
 5. Enable **Including all items below** if you want to restore any child nodes _below_ the selected node.
 6. Click **Restore**.
-7. Once the restore is completed, right-click the Content tree and select **Reload**.
+7. Right-click the Content tree and select **Reload** once the restore is complete.
 
 ![Partial restore](../../../umbraco-deploy/deployment-workflow/restoring-content/images/partialRestore-onEnvWithContent.png)
 
 {% embed url="https://www.youtube.com/embed/C5SnrEf78bQ?rel=0" %}
-Video example.
+A video showing how to use partial restores between Umbraco Cloud environments.
 {% endembed %}

umbraco-cloud/troubleshooting/deployments/merge-conflicts-on-flexible-environments.md

@@ -0,0 +1,72 @@
+---
+description: Merge conflicts can happen when the same schema has been modified in both the flexible environment and the mainline environment it's connected to.
+---
+
+# Merge Conflicts on Flexible Environments
+
+A merge conflict happens when a file or item contains conflicting changes in more than one environment during deployment.
+
+This guide explains how to resolve these merge conflicts and how to avoid them.
+
+## Resolving a Merge Conflict in a Flexible Environment
+
+The image below shows a merge conflict when pulling from the mainline environment to a flexible environment.
+
+![Pulling changes from the mainline environment failed](images/pulling-failed.png)
+
+To start debugging the merge conflict, a log file containing a list of conflicting files is provided. It's a `.txt` file that can be downloaded and viewed.
+
+### Preparations
+
+Before you start resolving the merge conflict, ensure you have the following things ready:
+
+* The log file containing a list of the conflicting files.
+* The clone link for the flexible (source) environment.
+* The clone link for the mainline (target) environment that flexible environment is connected to.
+* An editor that provides Git tools for handling merge conflicts (like Visual Studio Code).
+
+### Steps
+
+1. Download the log file provided from the failed pull (see image above).
+2. Clone the flexible environment [to your local machine](../../set-up/working-locally.md).
+3. Use the mainline environment clone link to add a new `git remote`:
+
+```git
+git remote add [mainline environment name] [mainline environment clone link]
+```
+
+4. Fetch the `master` from the added remote:
+
+```git
+git fetch [mainline environment name] master
+```
+
+5. Merge the `master` into the local clone.
+
+```
+git merge [mainline environment name]/master
+```
+
+6. Open the cloned files in your favorite editor that also provide Git tools.
+7. Go through the conflicting files one by one.
+8. Stage and commit the resolved conflicts.
+9. Push the change back to the flexible environment.
+
+Once the push to the flexible environment is complete, verify that the merge was successful.
+
+The final thing needed to be done is to complete the deployment to the mainline environment.
+
+{% hint style="info" %}
+In case you do not see your changes reflected on the flexible environment, [update the schema manually](../../deployment/deploy-dashboard.md#update-umbraco-schema-from-data-files) from the Umbraco backoffice. This will give you an idea of what is wrong enabling you to resolve it.
+{% endhint %}
+
+## Avoiding Merge Conflicts in a Flexible Environment
+
+A flexible environment is attached to a single mainline environment. Changes cannot be deployed from the flexible to the mainline environment, before changes from the mainline are pulled into the flexible environment.
+
+Learn more about how flexible environments work in the [Flexible Environments](../../getting-started/flexible-environments.md) article.
+
+Merge conflicts can be avoided by following these guidelines on the flexible environment:
+
+* Only work on schema specific to a single feature.
+* Do not make changes to schema regularly changed in the mainline environment.