Merge pull request #7015 from umbraco/flex/environmentReferences

Author: sofietoft

umbraco-cloud/deployment/README.md

@@ -6,9 +6,13 @@ description: >-
 
 # Deployment
 
-Umbraco Cloud uses a deployment model based on Git, Kudu, and Umbraco Deploy to move changes between environments. This follows a left-to-right model. Changes start in the local or left-most environment and are deployed to the production environment.
+Umbraco Cloud uses a deployment model based on Git, Kudu, and Umbraco Deploy to move changes between environments. This follows a left-to-right deployment approach. Changes start in the local or left-most environment and are deployed to the production/Live environment. This workflow is called the mainline.
 
-![Left to right model](images/left-to-right.png)
+The mainline environments are used when building and deploying the initial website. Upgrades, both manual and automatic also go through the mainline environments.
+
+Flexible environments can be used to work on features separate from the mainline. This is done without interfering with upgrades or other changes being worked on in the mainline.
+
+![Left to right model](images/left-to-right-approach.png)
 
 ## Deployment Approach
 
@@ -19,9 +23,6 @@ Umbraco Cloud separates schema and content during deployment. Schema includes Do
 
 ### Types of Deployments
 
-* **Schema Deployment:** Schema is stored in a Git repository. These are **deployed** between environments using a Git client or the Umbraco Cloud Portal.
-* **Content and Media Transfer:** Content and Media items are not stored in the Git repository. They must be **transferred** directly from the Umbraco backoffice using the **Queue for Transfer** option. Once queued, use the **Deployment** Dashboard in the **Content** section to complete the transfer.
-
 | Schema Deployments | Content and Media Transfers |
 | ----------- | ------------- |
 | Schema is stored in a Git repository. These are **deployed** between environments using a Git client or the Umbraco Cloud Portal. | Content and Media items are not stored in the Git repository. They must be **transferred** directly from the Umbraco backoffice using the **Queue for Transfer** option. Once queued, use the **Deployment** Dashboard in the **Content** section to complete the transfer. |

umbraco-cloud/deployment/images/left-to-right-approach.png

@@ -1,10 +1,10 @@
 # Baselines
 
-A Baseline Child project is very similar to a Fork (forked repository) on GitHub where we create a clone of an existing project while maintaining a connection between the two projects. The connection exists between the _Live_ environment of the existing project, the **Baseline project**, and the _Development_ or Live environment - of the newly created project, the **Child project**.
+A Baseline Child project is similar to a Fork (forked repository) on GitHub. A clone is created of an existing project while maintaining a connection between the two projects. The connection exists between the Live environment of the **Baseline project**, and the left-most mainline environment of the **Child project**.
 
 Any project can act as a Baseline project.
 
-The basic idea is that you have a project that contains all your standard Umbraco packages/components, maybe even configured with some default Document Types, which you want to use as a baseline for future projects. When you've made changes to your Baseline project, you can then push these changes out to all the Child projects with a click of a button.
+The basic idea is that you have a project that contains all your standard Umbraco packages/components. Some default Document Types which you want to use as a baseline for future projects is also configured. When you've made changes to your Baseline project, you push these changes out to all the Child projects with a click of a button.
 
 ![Baseline workflow](images/baseline-workflow.gif)
 
@@ -14,7 +14,7 @@ The basic idea is that you have a project that contains all your standard Umbrac
 Learn how to work with Baselines.
 {% endembed %}
 
-## Creating a Child Project
+## Create a Child Project
 
 To create a child project:
 

umbraco-cloud/deployment/images/left-to-right.png

@@ -28,7 +28,9 @@ When you need a specific configuration on Child projects, you should always use
 
 Here is a few examples of what could be transformed in the child sites.
 
-## Adding or updating appsettings (i.e. child-appsettings.web.live.xdt.config)
+## Adding or updating appsettings
+
+{% code title="child-appsettings.web.live.xdt.config" %}
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -45,7 +47,11 @@ Here is a few examples of what could be transformed in the child sites.
 </configuration>
 ```
 
-## Setting the SMTP settings for the child project (i.e. child-smtpsettings.web.live.xdt.config)
+{% endcode %}
+
+## Setting the Simple Mail Transfer Protocol (SMTP) settings for the child project
+
+{% code title="child-smtpsettings.web.live.xdt.config" %}
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -61,7 +67,11 @@ Here is a few examples of what could be transformed in the child sites.
 </configuration>
 ```
 
-## Setting custom rewrite rules for the child project (i.e. child-iisrewrite.web.live.xdt.config)
+{% endcode %}
+
+## Setting custom rewrite rules for the child project
+
+{% code title="child-iisrewrite.web.live.xdt.config" %}
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -86,12 +96,14 @@ Here is a few examples of what could be transformed in the child sites.
 </configuration>
 ```
 
-The above could either be added to its config files or be split up into one config file per setting. Umbraco Cloud will run through all the config files for the project. i.e. in one file
+{% endcode %}
+
+The above could either be added to its config files or be split up into one config file per setting. Umbraco Cloud will run through all the config files for the project.
 
-* child.web.live.xdt.config
+* `child.web.live.xdt.config`
 
 or having multiple files
 
-* child-appsettings.web.live.xdt.config
-* child-iisrewrite.web.live.xdt.config
-* child-smtpsettings.web.live.xdt.config
+* `child-appsettings.web.live.xdt.config`
+* `child-iisrewrite.web.live.xdt.config`
+* `child-smtpsettings.web.live.xdt.config`

umbraco-cloud/getting-started/baselines/README.md

@@ -7,7 +7,6 @@ description: Begin your journey with Umbraco Cloud by exploring the essentials.
 This section will help you get up and running with the core features of Umbraco Cloud. Whether you are new to Umbraco or migrating from another platform, these articles will walk you through everything you need to know to get started.
 
 
-
 <table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><a href="the-umbraco-cloud-portal/">The Cloud Portal</a></td><td>Learn how to log in, navigate the interface, and start managing your Umbraco projects.</td><td><a href="the-umbraco-cloud-portal/">the-umbraco-cloud-portal</a></td><td><a href="../.gitbook/assets/Documentations Icons_Umbraco_CMS_Fundamentals_Backoffice.png">Documentations Icons_Umbraco_CMS_Fundamentals_Backoffice.png</a></td></tr><tr><td><a href="project-overview.md">Project Overview</a></td><td>Understand how the Umbraco Cloud environment is structured and what each section of your project means.</td><td><a href="project-overview.md">project-overview.md</a></td><td><a href="../.gitbook/assets/Documentations Icons_Umbraco_CMS_Tutorials_Custom_Dashboard.png">Documentations Icons_Umbraco_CMS_Tutorials_Custom_Dashboard.png</a></td></tr><tr><td><a href="environments.md">Environments</a></td><td>Environments are the foundation of your Umbraco Cloud project. Learn how to set up and manage your environments.</td><td><a href="environments.md">environments.md</a></td><td><a href="../.gitbook/assets/Documentations Icons_Umbraco_Sustainability_Best_Practices_Infrastructure.png">Documentations Icons_Umbraco_Sustainability_Best_Practices_Infrastructure.png</a></td></tr><tr><td><a href="baselines/">Baselines</a></td><td>Learn how to create and manage baselines in Umbraco Cloud.</td><td><a href="baselines/">baselines</a></td><td><a href="../.gitbook/assets/Documentations Icons_Umbraco_CMS_Implementation_Composing (1).png">Documentations Icons_Umbraco_CMS_Implementation_Composing (1).png</a></td></tr><tr><td><a href="migrate-to-umbraco-cloud.md">Migrate to Umbraco Cloud</a></td><td>If you're moving from another platform or version of Umbraco, you'll want to understand the steps involved in migrating to Umbraco Cloud. This section covers everything from preparation to execution.</td><td><a href="migrate-to-umbraco-cloud.md">migrate-to-umbraco-cloud.md</a></td><td><a href="../.gitbook/assets/Documentations Icons_Umbraco_CMS_Reference_Querying_and_Models.png">Documentations Icons_Umbraco_CMS_Reference_Querying_and_Models.png</a></td></tr><tr><td><a href="git-repository-in-a-cloud-project.md">Repositories in a Cloud Project</a></td><td>Learn how to work with Git repositories, including setting them up, syncing, and managing changes.</td><td><a href="git-repository-in-a-cloud-project.md">git-repository-in-a-cloud-project.md</a></td><td><a href="../.gitbook/assets/Documentations Icons_Umbraco_CMS_Reference_Caching.png">Documentations Icons_Umbraco_CMS_Reference_Caching.png</a></td></tr></tbody></table>
 
 ## Also in this section

umbraco-cloud/getting-started/baselines/configuration-files.md

@@ -1,9 +1,9 @@
 # Repositories in a Cloud Project
 
-Each Umbraco Cloud project can have multiple environments: Development, Staging, and Live depending on your Cloud project plan. Each environment has its own git repository that is hosted on Umbraco’s Cloud platform.
+Each Umbraco Cloud project can have multiple environments: Mainline and Flexible Environments. Each environment has its own git repository that is hosted on Umbraco’s Cloud platform.
 
 {% hint style="info" %}
-Umbraco Cloud repositories are _only_ deployment repositories and should not be used as source code repositories.
+Umbraco Cloud repositories are only deployment repositories and should not be used as source code repositories.
 {% endhint %}
 
 Ideally, your Umbraco Cloud setup should look like this:
@@ -31,42 +31,40 @@ You need to put your custom code in a different source control repository of you
 {% endtab %}
 {% endtabs %}
 
-## A Git Umbraco Cloud source control repository with the locally cloned Umbraco project
+## A source control repository with the locally cloned Umbraco project
 
-We recommend creating a Cloud project with at least two environments: a Development environment and a Live environment. To work with a local copy of your site, you then clone down the Development environment using the **Clone project** option from the Cloud Portal and start building your website locally. This repository is different from your source control repository.
+It is recommended to create a Cloud project with at least two environments: a Live environment including one extra mainline environment. Work with a local copy of the site by cloning down the left-most environment. This repository is different from your source control repository.
 
-Once you're happy with the results or wish to see how your website has progressed, you push the changes back to the Development environment. If everything is working as expected you then deploy your changes to the Live environment.
+Once you're happy with the results or wish to see how your website has progressed, you push the changes back to the Cloud. If everything is working as expected, deploy your changes to the Live environment.
 
 {% tabs %}
 {% tab title="Umbraco 10+" %}
-#### Code Deployment Summary
+### Code Deployment Summary
 
 ![Umbraco Cloud Overview](images/UCP.png)
 
 In the above diagram, the Umbraco Git repository contains the source code of a class library CS project.
 
 With this setup, once you commit your code in the Umbraco Cloud Git repository, your C# source code is built by Umbraco Cloud and then deployed to the `wwwroot` folder.
 
-#### Disadvantages of using an Umbraco Cloud Project repository as a source code repository
+### Disadvantages of using an Umbraco Cloud Project repository as a source code repository
 
 * We only guarantee to maintain and keep the `master` branch. If there are any other branches, they might be removed without any notification causing data loss.
 * You will need to commit your frontend artifacts as the build pipeline only builds dlls from your C# code.
 {% endtab %}
 
 {% tab title="Legacy Umbraco 7 and 8" %}
-#### Code Deployment Summary
+### Code Deployment Summary
 
 <figure><img src="../.gitbook/assets/UCP_v8.png" alt=""><figcaption><p>Umbraco cloud overview Legacy versions</p></figcaption></figure>
 
 In the above diagram, the external git repository contains the source code of a class library CS project, if you had a class library project that was used in your Cloud project.
 
 With this setup, you commit your changes twice. Once to commit your code in your source control and the other commit to the Umbraco Cloud Git repository to deploy your website. Your source code is not hosted on Umbraco Cloud but only your cloned project will be in the Umbraco Cloud Git Repository. Your code is built and compiled into the cloned project and then pushed to Umbraco Cloud. Thus updating the site with your latest code changes.
 
-#### Disadvantages of using an Umbraco Cloud Project repository as a source code repository
+### Disadvantages of using an Umbraco Cloud Project repository as a source code repository
 
 * We only guarantee to maintain and keep the `master` branch. If there are any other branches, they might be removed without any notification causing data loss.
 * You will always need to commit your dll files.
 {% endtab %}
 {% endtabs %}
-
-##

umbraco-cloud/getting-started/explore-umbraco-cloud.md

@@ -117,7 +117,7 @@ You can create a new Umbraco Cloud project in one of the two ways:
 
 1. Click **Create project** in the Umbraco Cloud Portal.
 2. Choose **Umbraco Cloud** as the Type.
-3. Choose a **plan** that enables you to add a Development environment.
+3. Choose a **plan** that enables you to add an extra mainline environment.
 4. Select the **version** that matches the project you want to migrate.
 5. Give the project a **name**.
 6. Choose from which **Region** the site should be hosted.
@@ -128,10 +128,16 @@ You can create a new Umbraco Cloud project in one of the two ways:
 11. Check the "Terms and conditions" box.
 12. Click **Create Project**.
 
-Once the project is set up, **add a Development** environment. This will enable you to start over with the migration, should something go amiss.
+Once the project is set up:
+
+1. Select **Configure environments**.
+2. Add a new **mainline environment**.
+    * Throughout this guide, this mainline environment will be referred to as the **Development environment**.
+
+Having more than one environment on your project, will enable you to start over with the migration process should it be needed.
 
 {% hint style="info" %}
-Many processes happen in the background when a new Cloud environment is set up. It might take several minutes before the environments are ready to use.
+Many processes happen in the background when a new Cloud environment is set up. It might take some time before the environments are ready to use.
 {% endhint %}
 
 With the Cloud project set up and ready, the migration can start in the next step.
@@ -152,7 +158,7 @@ The Umbraco Cloud project is now ready for the next step where the two projects
 
 To continue the migration the next step is to clone down the Umbraco Cloud environment to merge it with the Umbraco CMS project.
 
-Follow the steps outlined in the [Working with a Local Clone](../set-up/working-locally.md#cloning-an-umbraco-cloud-project) article to clone down the **Development** **environment** of the Umbraco Cloud project.
+Follow the steps outlined in the [Working with a Local Clone](../set-up/working-locally.md#cloning-an-umbraco-cloud-project) article to clone down the Development environment on the project.
 
 {% hint style="info" %}
 Do not run the project after cloning it down.

umbraco-cloud/getting-started/git-repository-in-a-cloud-project.md

@@ -1,11 +1,9 @@
 # Best Practice for Working in Teams on Umbraco Cloud
 
-In this article, we will look at some of the best practices and recommendations when you are working in teams on your Umbraco Cloud projects.
+This article will look at some of the best practices and recommendations when you are working in teams on your Umbraco Cloud projects.
 
 ## Working with Git in Teams
 
-### Pull before you Push
-
 Always start by making a pull request from your project before you push anything back up to Cloud. This way you ensure that you do not accidentally overwrite the work that someone else in your team has worked with.
 
 ### Create branches locally
@@ -14,16 +12,18 @@ Umbraco Cloud is built on top of Git which means that you can create branches lo
 
 ## Working with Environments in a team
 
-### Set up a Development environment
+It is recommended to use multiple environments when you are working in teams. With additional environments, members of a team can work locally, pushing up changes to the Cloud environment for testing.
+
+Having multiple environments enables developers to continue developing, while content editors can focus on creating content in a separate environment.
 
-We highly recommend that you use a Development environment when you are working in teams. With the Development environment, members of a team can work on their local version of the project. They can then push back up to the development environment to be tested and approved before being deployed to either the staging or the live environment.
+### Flexible Environments
 
-### Set up a Staging environment
+When you need to work on a new feature, using a flexible environment ensures that the regular workflow isn't affected. The flexible environment is connected to a single mainline environment and isn't part of the left-to-right deployment workflow.
 
-When working in a bigger team with both developers and content editors, we highly recommend that you set up a Staging environment. This way the developers can continue developing in the Development environment, while the content editors can focus on creating delightful content in the Staging environment.
+Learn more about how this works in the [Flexible Environments](flexible-environments.md) article.
 
 ## Team development workflow On Cloud
 
-For a more in-depth example of how to work in teams on Umbraco Cloud projects, Our Gold Partner ProWorks have created an article about how they have set up a [Team development workflow on Umbraco Cloud](https://skrift.io/issues/integrating-umbraco-cloud-with-team-development-workflow/).
+For a more in-depth example of how to work in teams, our Gold Partner ProWorks has written an article on [Team development workflows](https://skrift.io/issues/integrating-umbraco-cloud-with-team-development-workflow/).
 
-This article can serve as inspiration if you are an agency and are looking into setting up a bigger project where several people will be working on Umbraco Cloud.
+This article serves as inspiration if you looking into setting up a bigger project where multiple people will be working on Umbraco Cloud.