Implementations which are not yet using Helix, and do not qualify for a full tear-down, may benefit from refactoring to the Helix architecture. @anderslaub has spoken on this topic and advocates for use of a "Legacy" layer to allow incremental refactoring.

Should Helix include recommended, incremental refactoring guidance? How have you approached Helix refactoring?

https://helix.sitecore.net/principles/templates/references.html

A templates class should never define constants for templates that are not created in the module itself. If a module needs to reference a template or field in another module, it should reference the Templates struct in that module.

This can be read to imply allowing feature-to-feature references. It should be clarified to provide examples of scenarios when this would apply (Feature-to-Foundation, Project-to-Feature).

Feedback on Helix and its use indicates that at times, developers get caught up in the specific practices and conventions, and get stuck when it's not clear how to follow them. There are also cases where Helix is seen merely as an organizational structure for projects. Understanding the core principles -- the "why" -- is actually more important than the conventions themselves to help overcome these issues.

The Helix Workshop gets rather deep on the Robert Martin principles which provided much of the foundation for Helix:

• Reuse-Release Equivalence Principle (REP)
• Common-Reuse Principle (CRP)
• Common-Closure Principle (CCP)
• Acyclic-Dependencies Principle (ADP)
• Stable-Dependencies Principle (SDP)
• Stable-Abstractions Principle (SAP)

These principles are also outlined in Chapter 28 of Agile Principles, Patterns, and Practices in C#.

Of only slightly lesser importance is the intention of Helix to provide a shared language across the community that can be used to "standardize" implementations. This includes layer naming, "interface" templates, etc.

There is some documentation on Architectural Principles in Helix already, but how do we better communicate the "why" of Helix? Is it a matter of moving this section to a more prime position? New content needed? Better/simpler explanations of the core principles?

As most of what FakeDb does can be accomplished through mocking, and as a 3rd party tool it may or may not be compatible with future versions, we should update Unit Testing documentation to remove it or to communicate this.

Related: Sitecore/Helix.Examples#67

The Definitions is somewhat belabored, focusing attention on double meanings that pose little actual confusion, such as the distinction between a C# Project and a project in the business or management sense. This section should either be eliminated or simplified.

Update for config layers, loading order. Server roles?

http://helix.sitecore.net/principles/configuration/managing-config-files.html

Hi. Is there a certain reason why structs were chosen to hold GUIDs of Sitecore templates and fields instead of static classes?
There are a few considerations I thought of:

1. It is possible to instantiate a struct, which can be confusing to allow. With static classes, the compiler will not allow to do that.

2. Microsoft recommends using static classes to define constants. Currently, the Helix documentation shows that the conventions define to choose only structs to clearly signal the Templates type’s unique function as a constants holder only. I believe it is, indeed, very important to indicate that, though a static class can fit here even better. In Microsoft's programming guide on how to define constants they actually suggest to use static classes. For even further description of it's purpose, class name qualifier can be made very self-descriptive, for example "TemplateConstants".

Furthermore, it can also be controversial that structures are used to hold constants only, according to this discussion on SO. In some other programming languages it could be true (like C/C++), but in C#, structures can have properties, methods and even implement interfaces.

3. memory usage, size and copying aspects - a general recommendation for a structure instance size is to be less than 16 bytes, mostly because of copying aspects that can negatively impact the performance. Even though it is very unlikely that someone would decide to assign  the Templates structure to a variable (or to pass it to a method), still it does not seem to be prudent not to adhere to Microsoft's recommendation  to avoid defining a structure when it has an instance size more than 16 bytes. In our case, the structure contains only reference types and field-by-field copy is made (only references, not the objects itself). Considering that one object reference is 8 bytes in x64, usually, this recommendation is not met.

4. I've asked about this on #helix-habitat on Sitecore Community Slack and there was common agreement among the community members that static classes are more suitable for such purpose . And I received recommendation to open an issue for that.

Do you think that indeed it will be better to use static classes to hold template GUIDs, instead of structs? Should I create a pull request for this?

Thank you.

Helix docs should be moved to https://helix.sitecore.com to align with the rest of Sitecore web properties, and appropriate redirects configured.

Helix should include recommended practices for Sitecore XConnect, which provide for long-term maintainability and shared conventions across the community.

• Sitecore XP development may require developing on, and deploying to, multiple targets/subsystems. This is a general concern discussed in #22 and addressed by @robearlam for Commerce in this pull request.
• Any recommended practices for schema design?
• Any recommended practices for schema deployment to all necessary services?
• Any specific practices around use of Tracker or Universal Tracker?
• Other conventions/best practices which Helix should document?

With the new Basic Company Helix Examples going public, any Habitat references in existing docs which can be replaced with Basic Company should be removed and replaced.

Below is a quick audit of Habitat mentions. Not all can be replaced immediately due to the limited scope of Basic Company.

• Layers section (2.1.2)
  • Foundation subsection (2,1,2,3) - Basic isn't deep enough in the Foundation layer
• Modules section (2.1.3)
• Domain language section (2.1.4) - Maybe needs to wait for a larger example?
• Implementation structure (2.2.1) - Maybe needs to wait for a larger example?
• Solution structure (2.2.2)
• Projects (2.2.3)
• Module structure (2.3.2)
• Item types (2.4.1)
• Managing items in development (2.4.2)
• Deploying items (2.4.3) - Remove existing for now, add Azure deployment to Basic later?
• Template Structure (2.5.1)
• Template Types (2.5.3) - Can't replace all, maybe should wait?
• References from code (2.5.4) - Also could fix #26 and #19
• Layouts and sublayouts (2.6.1) - No "sublayouts" in Basic
• Datasource Settings (2.6.3) - Too simple in Basic, will want to complete #30 first
• Rendering Params (2.6.4) - Don't think we have these in Basic yet
• Placeholders (2.6.5) - Basic doesn't really have enough
• Configuration definition scope (2.7.2) - No settings in Basic
• Managing config files (2.7.4) - Could do config patches but don't have web.config transforms in Basic, maybe wait
• Tenants (2.8.1) - No multisite in Basic
• Sites (2.8.2) - No multisite in Basic
• Enabling multi-language (2.9.1) - No languages in Basic
• Dictionary (2.9.2) - Basic uses builtin dictionary, wait until we have a custom example and feature both
• Security rights management (2.10.1) - No security roles in Basic
• Domains (2.10.2) - No custom domains in Basic
• Code formatting (2.11.1) - No editor settings or .DotSettings in Basic
• Front-end technologies (2.12.1) - no integrated front-end example yet
• HTML markup (2.12.2) - No integrated front-end yet
• CSS and Theming (2.12.3) - No integrated front-end yet
• Scripting (2.12.4) - No integrated front-end yet
• Setting up local dev (3.1.1) - Change to powershell and SIF?
• Local deployment (3.1.2) - Change to mention TDS and HPP
• Version control (3.1.3)
• Integration (3.2.2) - Should set up something automated for Helix Examples
• Managing tests (3.3.1)
• Unit tests (3.3.2)
• Integration tests (3.3.3) - Maybe remove since outdated?
• Deployment strategy (3.4.1) - Remove since outdated?

As Sitecore XP continues to introduce independent services split off from the "monolith," there is an increasing need to be able to deploy to multiple targets, both locally and in test/production. This includes Sitecore Commerce, XConnect / Marketing Automation, and the new Identity Service. Helix should include recommended practices for solution structure and deployment to these multiple targets.

The Commerce Pull Request from @robearlam provides some foundation for this when using VS Projects to define module boundaries. How would this be handled in alternate solution structures (#21), such as project-per-layer?

Improves readability. reStructuredText uses a double-tick `` for this.

It has become very clear that the Helix documentation should include some scenario-based narratives that give guidance on how to follow the practices and adhere to the core principles. Feature-to-Feature communication in particular (via unification in the Project layer, or abstraction/inversion in the Foundation layer) would seem to be a great place to start.

What other scenarios, patterns, etc. would be helpful to document in the form of recipes or how-to's?

This is a lot of reading for what's not really solution architecture, but development best practice:

https://helix.sitecore.net/devops/development/version-control.html

At the very least, I think this section could be drastically slimmed down.

Helix feedback has included a desire for more guidance on multi-site implementation, specifically the ability to implement site-specific designs. This is a complex topic as multi-site implementation approaches can vary significantly.

• Can the sites share semantic markup, and thus share Features, and then use CSS to vary design? Feedback is that this often sounds better in concept than it works in practice.
• Can the sites share Feature back-end code (Controllers, Models, Services, etc), then vary markup by Site/Project via MVC Areas or other techniques? This sort of reuse can lead to exception logic, testing difficultly, and other increased maintenance cost as a change to a Feature now impacts multiple sites.
• Should the sites be implemented independently (even copying logic) with only essential shared infrastructure placed in the Foundation layer? Site-specific Feature modules can be placed in Module Groups.

There will obviously be multiple approaches to document as no single one will fit all requirements. What are the most effective strategies? And are there other multi-site concerns not currently covered by Helix?

http://helix.sitecore.net/principles/layout/layouts.html#layouts-and-sub-layouts

• Needs update for Sitecore 9
• Keep a link to community implementation for 8.x

The Helix guidelines on solution structure and the Habitat example both utilize Visual Studio Projects to help define and enforce module boundaries and dependencies. While many in the community utilize this approach, much of the feedback around Helix has centered on the overhead of utilizing Visual Studio Projects in this way -- module creation, solution load time, build time, deployment complexity, dependency upgrades, etc. Though tooling and proper build configuration can help with this, there are reasonable arguments that this level of structure is not needed for all solutions.

Many developers utilize a "project-per-layer" approach, potentially using FxCop rules to help enforce module boundaries. Though this somewhat violates Common Closure, it likely can achieve the same maintainability goals for many/most Sitecore implementations. There is also potential for a hybrid approach, using a project-per-module just in the Foundation layer, since dependency management requires more care in the Foundation (which allows dependencies between modules in the same layer).

Should Helix documentation and examples include the project-per-layer approach?

Helix already includes some guidance on DevOps and development lifecycle management. However we have received feedback that Helix needs more content/guidance on these topics. What are the gaps here that need to be addressed?

Modular / partial deployments come up a lot with Helix, even though it's explicitly stated to be not a goal of the architecture. How often do your implementations merit this, and does the typical partner/customer have the DevOps expertise and infrastructure to implement?

Helix currently recommends the use of Interface Templates (in the Feature Layer) to construct Datasource Templates (in the Project Layer):
https://helix.sitecore.net/principles/templates/template-types.html#datasource-template

This makes the Datasource Template itself project-specific, and means that any new component requires defining at least two templates. The question has been raised as to whether this is premature architecture (YAGNI) for a typical Sitecore implementation.

Reasons for needing a separate project-level Datasource Template include:

• Use of an interface template means the Feature (rendering) itself can be unaware of whether the data is coming from the Page itself or a Datasource. (YAGNI?)
• Allows for configuration of site-specific standard values.
• Allows for configuration of site-specific workflows on Datasource templates.
  • Probably the most likely scenario. Though workflows on datasource items are currently confusing in the Sitecore UX, they are quite necessary at times.

The question is, should Helix specifically call out use of Interface templates for Datasources as a conditional recommendation, if the above scenarios are not requirements? Yes they could become requirements later, but is the refactoring effort that significant?

Helix should include recommended practices for Sitecore Experience Commerce, which provide for long-term maintainability and shared conventions across the community.

• Sitecore Commerce development requires developing on, and deploying to, multiple targets/subsystems. This is a general concern discussed in #22, and addressed by @robearlam in this pull request.
  • Or should Commerce code remain in a separate VS Solution? Does this violate Common Closure, or does it make intention clearer?
• Any recommended practices for plugin development / dependencies?
• Any specific practices around use of the Storefront?
• Any general e-commerce best practices we should incorporate w/r/t integration, etc?
• Other conventions/best practices which Helix should document?

Clarification: This is about practices and conventions that achieve the goals of modular architecture. maintainability, and discoverability, not necessarily about shoehorning Commerce into XP Helix practices. Open to any ideas which achieve these goals.

There is some desire in the community to rename the Project layer due to confusion with Visual Studio projects. Ideas include:

• Site
• Tenant
• Context

Doing this will need to be weighed against the documentation updates it will require, community confusion it may create, and upgrade headaches from item and folder renames.

Is this needed, and is it worth it?