diff --git a/source/by-role/developer/devcontentops.rst b/source/by-role/developer/devcontentops.rst index 8b0c460b5..65f0fc022 100644 --- a/source/by-role/developer/devcontentops.rst +++ b/source/by-role/developer/devcontentops.rst @@ -120,7 +120,7 @@ addresses this problem. For the single repository approach, the branches will look like the following .. list-table:: - :widths: 10 45 45 + :widths: 14 43 43 :header-rows: 1 * - Branch @@ -175,7 +175,7 @@ Given the environments listed above, for the one upstream repository per environ dev - \- |br| QA/qa - * - Develepor A Fork + * - Developer A Fork - studio-dev |br| dev-a-fork - \- |br| @@ -188,7 +188,6 @@ The repositories are set up as forks of one another. Depending on your external """" Flow """" - Referring back to the figure above, code flows following the steps - The developer forks the *Dev* repository's *dev* branch creating *dev-a-fork* @@ -209,6 +208,68 @@ Referring back to the figure above, code flows following the steps - To deploy and test the code on the shared development environment, code flows from *dev* to *studio-dev*, and is then pulled into Crafter Studio. - Code is similarly pushed from *dev* to *qa* and again to production (see diagram above) +"""""""""""""""""""""""""""""""""""" +Using the Git Project Tool in Studio +"""""""""""""""""""""""""""""""""""" +The steps above describe code and content moving between Git branches and external repositories. On each Crafter Studio authoring environment, the :ref:`Git project tool ` is how developers and DevOps personnel sync the project's sandbox repository with those shared branches. + +Open it from the **Sidebar** by clicking on |projectTools|, then **Git**. From there you can add a remote repository, pull changes into Studio, and push sandbox commits to a remote when appropriate. For UI walk-throughs of each operation, see :ref:`project-tools-git`. + +The Git project tool is typically used **after** branch promotion work has been done in your Git server (merge, pull request, or fast-forward on the target branch). Studio pulls the result into the authoring environment so authors and developers can preview and test against the updated sandbox. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example: Deploy Code to Delivery Dev +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +After a feature branch is merged into *dev* (code forward) and the *studio-dev* branch is updated on the Git server: + +#. On the ``Authoring Dev`` (the authoring environment), ensure the project is linked to the upstream repository (see :ref:`create-project-based-on-a-blueprint-then-add-a-remote-bare-git-repository` if the remote is not yet configured). The upstream repository should be the *studio-dev* branch on *Dev* on the ``Git Server``. +#. In the Git project tool, pull from the remote branch that tracks *studio-dev* (or the branch your team uses for the Dev Studio sandbox), by clicking on the down arrow next to the remote repository branch that tracks the *studio-dev* branch on the ``Git server``. +#. Review the changes in Studio, then publish as needed so Delivery Dev is updated. + +This corresponds to the step in the flow :ref:`above ` where code moves from *dev* to *studio-dev* on the Git server and is then pulled into Crafter Studio in ``Authoring Dev``. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example: Promote Code to QA or Prod +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The same pattern applies when promoting code forward to QA and Prod: + +#. Merge or promote code on the ``Git Server`` (for example, from *dev* to *qa*, or from *qa* to *prod*) via a PR. +#. On the **QA** or **Prod** authoring environment, use the Git project tool to pull the updated *studio-qa* or *studio-prod* branch on the ``Git Server`` into Studio by clicking on the down arrow next to the desired remote repository branch. +#. Validate in Studio (and Staging, if enabled), then publish to the target delivery environment. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example: Sync a Developer Workstation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When a developer creates an orphan project from *dev-a-fork* or needs to align a local Studio sandbox with their fork: + +#. Add the developer's fork as a remote in the Git project tool on the ``Developer Workstation``. +#. Pull from the *dev-a-fork* branch (or the feature branch being actively developed). +#. Continue Studio-side work, carrying patches to the local *feature-x* branch in the IDE as described above. + +To publish IDE work back to the shared flow, push from the workstation to the fork and open a pull request into *dev*—not directly into *studio-dev* on the ``Git Server``. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example: Pull Content Back into Studio +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +After a *Content Back* operation syncs production content from *studio-prod* into *prod* then *prod* to *dev* (or *qa*) on the ``Git Server``, the updated content must still be pulled into the lower authoring environments: + +#. Confirm the content merge landed on the target branch in your ``Git Server``. +#. On the **Dev** or **QA** authoring environment, pull that branch into Studio using the Git project tool, by clicking on the down arrow next to the desired remote repository branch. +#. If blob storage is in use, sync blob content separately as described in :ref:`Blob Storage and Content Back ` below. + +.. note:: + *Content Back* merges happen on the *dev*, *qa*, or *prod* branches—not by pulling from *studio-qa* into *qa* or from *studio-dev* into *dev*. The Git project tool pulls **into** Studio; it does not replace the Git server-side promotion steps described earlier. + +~~~~~~~~~~~~~~~~~~~ +Important Practices +~~~~~~~~~~~~~~~~~~~ +- **Pull into Studio; promote in Git.** Use your external Git service for merges, pull requests, and branch protection. Use the Git project tool to bring the result into Studio's sandbox. +- **Respect path conventions.** Avoid pushing author-owned paths (such as ``/site/*`` and ``/static-assets/content/*``) from lower environments upstream. See the path conventions in the next section. +- **Resolve conflicts locally when possible.** If a pull into Studio reports a conflict, prefer resolving it on a developer workstation or in your Git service, then pull again. The Git project tool provides basic conflict options for emergencies; see the note in :ref:`project-tools-git`. +- **Publish after pulling.** A successful pull updates the sandbox repository. Use **Project Tools → Publishing** to deploy pulled changes to preview or delivery targets when required (see :ref:`project-tools-git`). + +| + """"""""""""""""""""""""""""""""""""""""""""""""""""""" What Should and Shouldn’t Be Moved Between Environments """"""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -304,6 +365,8 @@ If developers or QA personnel have created content items with the same path as p These conflicts can be resolved exactly the same way as code conflicts. The simplest resolution would be to accept the content coming from *dev* or from *qa*. Still, the repository will be able to handle selecting the item that's present in the *studio-* branches as well. Just keep in mind that production content won't make it to the CrafterCMS environment because of the way the conflict was resolved. +.. _devcontentops-blob-storage-content-back: + """"""""""""""""""""""""""""" Blob Storage and Content Back """""""""""""""""""""""""""""