Merge pull request #35 from Sitecore/feature/33/helix-examples-refere…

…nces

[#33] Update what we can in Helix Docs to reference Helix Basic Company

helix/devops/development/local-deployment.rst

@@ -3,8 +3,8 @@ Local deployment
 
 One of the most frequently asked questions when working with Sitecore is
 whether to develop locally inside the web root or outside. Although the
-general recommendation is to work outside the web root, a general
-qualification is needed.
+general recommendation is to work outside the web root, you should
+consider the implications.
 
 There are two major aspects which should lead to choosing one or the
 other:
@@ -15,8 +15,7 @@ importance of this separation cannot be overstated, as it will help in
 many aspects in the long run, such as general development,
 troubleshooting, upgrades and more. This separation is easier if the
 implementation specific files are physically separated from the files in
-the standard frameworks etc. On the other hand, tools and processes
-might cater for this separation, even when working inside the web root.
+the standard frameworks etc.
 
 Generally, if tasks that are repeated frequently become taxing, they
 will be circumvented – and this will lead to inconsistencies in the
@@ -28,15 +27,39 @@ frequency of this task it is imperative that this is easy. Tools and
 automated scripts can help this to become almost transparent for the
 developer.
 
-.. admonition:: Habitat Example
+.. admonition:: Sitecore Helix Examples - Sitecore TDS
 
-    The build system in Habitat includes a number of tasks that will watch
-    files of a given type and deploy these automatically to the local
-    instance. This includes changes to assemblies after a build, changes to
-    .cshtml view files and changes to .css files. Habitat also includes
-    tasks for deploying all files of a given type.
+    The Sitecore TDS version of Helix Basic Company uses the built-in
+    `capability of TDS <http://hedgehogdevelopment.github.io/tds/chapter4.html>`__
+    to deploy files to the web root on build. To avoid the need for a
+    TDS project for modules which do not have associated items, a single
+    TDS project is used to build and deploy files for all solution modules.
 
-        .. figure:: _static/image43.png
+        .. figure:: _static/basic-company-tds-deployment-sources.png
 
-            Figure: All gulp tasks as available through the Visual Studio
-            Task Runner
+            Figure: Source web projects for file deployment
+
+        .. figure:: _static/basic-company-tds-deployment-build.png
+
+            Figure: File deployment location, originating in the ``TdsGlobal.config``
+
+    You can also enable the *Content File Sync* feature of Sitecore TDS to automatically
+    deploy changes to any content files, such as Razor views and CSS/JS files.
+
+        .. figure:: _static/tds-content-file-sync.png
+
+            Figure: Configuring *Content File Sync* in *Tools > Options > TDS Options*.
+
+.. admonition:: Sitecore Helix Examples - Unicorn
+
+    The Unicorn version of the Helix Basic Company uses the
+    `Helix Publishing Pipeline (HPP) <https://github.com/richardszalay/helix-publishing-pipeline>`__
+    open source tooling to enable publishing of the entire Helix solution as a
+    single unit, and to enable auto-publish to the web root on build.
+
+        .. figure:: _static/basic-company-unicorn-hpp-reference.png
+
+            Figure: Helix Publishing Pipeline reference in Helix Basic Company - Unicorn
+
+    For information on configuring auto-publishing with HPP, see its
+    `documentation <https://github.com/richardszalay/helix-publishing-pipeline>`__.

helix/devops/development/setting-up.rst

@@ -1,26 +1,16 @@
 Setting up a development environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Optimising the task of setting up a local development environment is not
-just about on-boarding new developers or resetting a developer’s local
-environment – although these tasks can be important to optimise. It is
-also – and sometimes more importantly – about being able to consistently
-and quickly set up a given version of the complete clean implementation
-for testing and troubleshooting.
-
-Typically, after the initial build phase – where there often is an
-abundance of resources – comes the support or extension phase. In this
-phase, where there are often fewer resources and maybe even less
-experience with the implementation and processes, there is often a need
-for working on multiple branches at the same time, testing on
-production-like environments, the need to establish troubleshooting
-environments, etc. and so the need to quickly spin up a specific version
-of the local development environment increases.
-
-Setting up a local developer machine with a running environment can be
-more or less complex given business requirements and dependencies, but
-the following is an example of the tasks that could be involved and
-example of what each might contain:
+The task of setting up a local development environment is
+a critical optimization point for on-boarding new developers
+or resetting a developer’s local environment. It is also
+about being able to consistently and quickly set up a given version
+of the complete clean implementation for testing and troubleshooting.
+This is especially the case during the support phase of a project,
+where there are often fewer resources with less experience, who need to
+quickly spin up a specific version of the local development environment.
+
+Typical steps of a development environment setup might include:
 
 Check out
     Get the required branch or version from the version control.
@@ -40,7 +30,7 @@ Build
 Baseline
     Set up a running website/environment based on a clean Sitecore or a defined baseline
 
-    *For example: Install a local Sitecore setup, for example through SIM, PowerShell or similar. This may involve restoring backup databases with production-like test data. This may also involve restoring a virtual machine with the full running environment.*
+    *For example: Install a local Sitecore setup, for example through Sitecore Installation Framework (SIF). This may involve restoring backup databases with production-like test data. This may also involve restoring a virtual machine or containers with the full running environment.*
 
 Publish
     Publish the modules to the baseline website
@@ -61,20 +51,42 @@ It is recommended that you automate these steps as far as possible. This
 will increase productivity and quality in both the short and especially
 the long run.
 
-.. admonition:: Habitat Example
+A task runner framework of some kind can be very useful in automating this process.
+
+.. admonition:: Sitecore Helix Examples
+
+    The Sitecore Helix Examples take advantage of a PowerShell-based task runner
+    which Sitecore developers are going to be using anyway -- the Sitecore Installation Framework (SIF).
+    The examples use SIF to manage the Sitecore install and configuration, as well
+    as solution builds and item deployment (particularly when using Unicorn). **The
+    install and build system is optimized for the deployment of multiple examples and
+    thus is likely more complex than needed for most solutions.** However, you may find
+    SIF to be a useful task runner for your own solution as well. See there
+    `SIF Configuration Guide <https://dev.sitecore.net/Downloads/Sitecore_Installation_Framework/2x/Sitecore_Installation_Framework_210.aspx>`__
+    for information on creating custom SIF configurations and tasks.
+
+    .. figure:: _static/basic-company-unicorn-sif-tasks.png
+        :scale: 75%
+
+        Figure: Custom SIF configuration for build and item deploy in Helix Basic Company - Unicorn
+
+.. admonition:: Habitat Home
+
+    The *Habitat Home* marketing demo sites utilize the popular C#-based task runner,
+    `Cake (C# Make) <https://cakebuild.net/>`__. You can see
+    `examples in the Habitat Home repository <https://github.com/Sitecore/Sitecore.HabitatHome.Platform/blob/master/build.cake>`__.
+
+.. admonition:: Habitat
 
-    Habitat includes an example of an almost fully automated local
-    environment configuration using a combination of various tools. The
-    overall build system uses `Gulp <http://gulpjs.com/>`__, which can be
-    triggered through the `Visual Studio Task
+    The "original" Sitecore Helix example, Habitat, used `Gulp <http://gulpjs.com/>`__,
+    as a task runner to build and deploy, which can be triggered through the `Visual Studio Task
     Runner <https://blogs.msdn.microsoft.com/webdev/2016/01/06/task-runners-in-visual-studio-2015/>`__.
 
-    Please note that the Habitat example site has all content versioned
-    through the version control system – unlike a production environment in
-    which content is managed in production – and can therefore use a clean
-    Sitecore installation as the baseline.
+    Though not as familiar to .NET developers due to the use of JavaScript-based
+    tasks, Gulp may still be a good tool for teams who also need to automate front-end
+    development tasks such as executing webpack configurations.
 
-        .. figure:: _static/image42.png
+    .. figure:: _static/habitat-gulp-task-runner.png
 
-            Figure: Running the Publish task through the Visual Studio Task
-            Runner
+        Figure: Running the Publish task through the Visual Studio Task
+        Runner

helix/devops/development/version-control.rst

@@ -35,39 +35,19 @@ As much as possible, avoid adding standard frameworks and standard files
 to version control. This includes the implementation web.config and
 standard Sitecore config files (see :doc:`/principles/configuration/managing-config-files`).
 
-There are a number of package managers, for example NuGet, Bower,
-node/npm, that are useful to help install and integrate external
+There are a number of package managers, for example NuGet and npm,
+that are useful to help install and integrate external
 frameworks for different purposes. These all largely use the same
 approach. They require a manifest file that points to the required
 versioned packages. This manifest can be versioned alongside your
 implementation specific files to allow your system to pull in the
 packages from external repositories.
 
-.. admonition:: Habitat Example
+.. admonition:: Sitecore Helix Examples
 
-    Habitat uses NuGet packages for .NET dependencies and Bower for
-    front-end technologies. The build system in Habitat is based on gulp and
-    node.js, and therefore uses the node.js Package Manager (npm) for build
-    script dependencies.
-
-Some external dependencies, for example Sitecore itself, cannot
-immediately be integrated via a standard package manager such as NuGet –
-or might require custom configuration to be integrated correctly. For
-this purpose, consider building custom scripts that automate the
-integration or configuration of the dependencies. Remember to version
-these scripts (either in the version control system itself or through a
-package manager manifest) as part of your implementation.
-
-.. admonition:: Habitat Example
-
-    Build scripts in Habitat are versioned as part of the implementation,
-    and have a simple task for pulling in Sitecore dependent assemblies for
-    the build.
-
-Note that there are approaches to adding the Sitecore assemblies to a
-local NuGet repository. One option is to use the Sitecore Instance
-Manager
-(https://marketplace.sitecore.net/en/Modules/Sitecore_Instance_Manager.aspx).
+    The Helix Examples use NuGet packages for .NET dependencies and npm for
+    front-end technologies. For Sitecore assemblies, the examples reference
+    the `Sitecore public NuGet feed <https://doc.sitecore.com/developers/90/sitecore-experience-manager/en/sitecore-public-nuget-feed-faq.html>`__.
 
 Environment specific settings
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

helix/devops/integration/integration.rst

@@ -18,8 +18,8 @@ Depending on your tools stack – version control, configuration
 management, item serialization etc. – various tools can help you with
 the integration of your modules and solutions into a distributable
 package. The format of this package will depend on the deployment
-strategy and tools you choose. For example, Team Development for
-Sitecore covers the complete application lifecycle from development
+strategy and tools you choose. For example, Sitecore TDS
+covers the complete application lifecycle from development
 through to integration, and supports generation of Sitecore Update and
 NuGet packages that can be automatically installed with for example
 `Octopus Deploy <https://octopus.com/>`__.

helix/devops/testing/integration-testing.rst

@@ -11,7 +11,7 @@ Therefore, the tests belong in the Project layer as opposed to together
 with the module in the Feature or Foundation layer.
 
 Code and other files related to tests – independent of whether they are
-unit tests or other testing methodologies – belong in the /tests folder
+unit tests or other testing methodologies – belong in the ``/tests`` folder
 under the respective module.
 
 A single implementation can consist of multiple Visual Studio solutions.
@@ -20,10 +20,10 @@ the unit tests) in a separate solution than the code.
 
 .. admonition:: Habitat Example
 
-    Habitat has a whole range of acceptance tests built with SpecFlow. These
+    Previous versions of Habitat featured acceptance tests built with SpecFlow. These
     are generally structured to test the functionality within a single
     module. But since they rely on the integrated Habitat website to run,
-    they are all located in the *Habitat* project layer module.
+    they were all located in the *Habitat* project layer module.
 
     .. figure:: _static/image47.png
 

helix/devops/testing/managing-tests.rst

@@ -2,12 +2,12 @@ Managing Tests
 ~~~~~~~~~~~~~~
 
 All tests, independent of testing methodology or technology, should be
-located in the /tests folder under the corresponding module. If there
+located in the ``/tests`` folder under the corresponding module. If there
 are multiple testing methodologies for one module, for example unit
 testing and integration testing, the module can contain sub-folders.
 
-.. admonition:: Habitat Example
+.. admonition:: Sitecore Helix Examples
 
-    .. figure:: _static/image45.png
+    .. figure:: _static/basic-company-navigation-tests.png
 
-        Figure: Tests folder under the Forms module in Habitat
+        Figure: Tests folder under the Navigation module in Helix Basic Company

helix/devops/testing/unit-testing.rst

@@ -1,48 +1,27 @@
 Unit tests
 ~~~~~~~~~~
 
-There is a fair number of unit testing approaches and frameworks for
+There are a fair number of unit testing approaches and frameworks for
 .NET and Sitecore, but as with other technologies and methodologies,
 Helix does not dictate which to choose. We do emphasise the value of
 adding unit tests to your business logic, and highly encourage the
 general practice.
 
-On disk, unit test projects should be contained in the /tests folder
+On disk, unit test projects should be contained in the ``/tests`` folder
 below the module folder. In Visual Studio the unit test project should
 be in the same Visual Studio solution as the corresponding module
 projects and contained with the module solution folder.
 
-.. admonition:: Habitat Example
+.. admonition:: Sitecore Helix Examples
 
-    .. figure:: _static/image46.png
+    .. figure:: _static/basic-company-navigation-tests-visualstudio.png
 
         Figure: Unit Test Project in Visual Studio
 
-.. admonition:: Habitat Example
-
-    Unit Tests in Habitat are developed as Arrange-Act-Assert and uses the
+    Unit Tests in Helix Examples are developed as Arrange-Act-Assert and use the
     following modules:
 
-    -  xUnit (https://xunit.github.io) framework as the main unit testing framework
-    -  NSubstitute (http://nsubstitute.github.io/) for mocking objects
-    -  AutoFixture (https://github.com/AutoFixture/AutoFixture) for “Arranging” the unit tests
-    -  FluentAssertions (http://www.fluentassertions.com/) for the assertion syntax
-    -  FakeDb (https://github.com/sergeyshushlyapin/Sitecore.FakeDb) for faking Sitecore objects and services
-
-    Example of a Habitat unit test for Sitecore.Feature.Language.LanguageRepository:
-
-    .. code-block:: csharp
-    
-        public class LanguageRepositoryTests
-        {
-            [Theory]
-            [AutoDbData]
-            public void GetActive_ShouldReturnLanguageModelForContextLanguage(Db db, [Content] DbItem item)
-            {
-                var contextItem = db.GetItem(item.ID);
-                Context.Item = contextItem;
-                var activeLanguage = LanguageRepository.GetActive();
-                activeLanguage.TwoLetterCode.Should().BeEquivalentTo(Context.Language.Name);
-            }
-        }
+    -  `xUnit <https://xunit.github.io>`__ framework as the main unit testing framework
+    -  `Moq <https://github.com/moq/moq4>`__ for mocking objects
+    -  `FakeDb <https://github.com/sergeyshushlyapin/Sitecore.FakeDb>`__ for faking Sitecore objects and services