RFC: Sitecore Experience Commerce Recommended Practices

[nickwesselman]

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 RFC: Multiple Deployment Targets #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.

[akshaysura]

Use the Visual studio plugin provided by the Commerce SDK, it creates the folder structure needed for plugins. Makes it easy to segregate code.

On the XP side of commerce you can use the Helix principles to build projects.

[ezlateva]

hey guys, I have to be honest in saying that I don't have that much experience actually developing engine plugins, but I did do quite a lot in maintenance/test/debug mode.. and to me, there's very little if any benefit of having plugins and website components sit in the same solution

The plugins and the engine are a separate app to me, and even during development, you're unlikely to be working on both the engine and the website at the same time. Typically, you'll develop plugins first, debug them, test them against API calls, etc.. once you're effectively done, you'd publish the engine and regenerate any service proxy references that 'front end' components can start using .. so to Sitecore, Commerce is an API, and the website is just a consumer (one of its many possible consumers I suppose), and if I were developing any other service API, it would live in its own solution, completely separate of any consumers

[robearlam]

The issue I have with splitting the two apart is that they are very much related. You may well create the Engine functionality first and test with Postman before creating the consumers, be that Web, Mobile or whatever else, but that doesn't mean there isn't a dependency.

If you at a later date have to change the Engine implementation due to changing business requirements then you will more than likely have to change the consumers as well, which means that according to the common closure principal they should live together.

I can understand having subset solutions that only contain projects for a specific target e.g. Engine, Web, Mobile etc as some developers like to work that way, but I firmly believe that the main solution should be a master solution that brings all of these together.

A lot of commerce features will have logic that executes in both the engine & the consumers, and the master solution should group all of these together. In the same way we see code & serialisation grouped together in Helix today, you may not have to use the serialisation functionality every time you touch the code but the dependency between the two implies they should live together and I believe that the commerce code should be handled in the same way.

This is also related to the RFC around Multi-deployment targets, we want to make sure that our targets moving forwards are handled in a uniform way as we introduce more and more micro-services to the architecture. We don't want to end up in a place where we have separate unrelated solutions for each service or it could become a bit of a dependency nightmare.

[nickwesselman]

Some relevant content:
https://www.sitecore.com/webinars/architect-your-ecommerce-shop-using-helix

[kazimnami]

I completely agree with @robearlam.

Having worked on a number of Sitecore Commerce implementations it is far better to start with a single repo and single solution.

Depending on team structure and size, individual solutions should be used. But this more to be used in situations where a team is only focused on search and they can have all their website and commerce projects included in the single solution.

Like Rob mentioned, there is a hard dependency between website and commerce projects. The Sitecore.Commerce.ServiceProxy project is the glue that binds the two. If the engine endpoints change, this project needs to change and be referenced in the website projects.

Both website and engine projects need to be developed together, versioned together and deployed together. No two ways about it.

This response was created on the run so apologies in advance :)

[Jonne]

In my team we also like to keep them together. This is great for discoverability and I have to agree with @robearlam and @kazimnami: in our experience they are also tightly coupled. Often when you have to add a field to a commerce component, you will also have to re-generate the service proxy and modify the related XP module. We have a customized build script that allows us to easily publish both the engine and website or to publish them individually.

In our experience, the only downside to this approach is that you lose the ability to use the NuGet consolidate feature. These different types of projects will reference different versions of NuGet packages. We haven't found this to be that big of a deal, but you could always add 2 additional solutions that contain all the specific types of projects, that you would use for package consolidation.

[raytran-sitecore]

In a true microservice world it might make sense to separate the XP and Commerce Engine codebase into separate solutions / repositories and govern them under different release strategies.

But as @robearlam and @kazimnami have stated, these two systems are tightly coupled. Therefore, separating these codebases will result in an increased risk in making a change that will have unintended consequences.

Keeping the codebase integrated will lead to a natural convention to treat these two systems as a congruent unit in the development cycle.

[dsolovay]

My practical exposure to Commerce is limited, so I am inclined to deffer to @robearlam, @Jonne, and @raytran-sitecore. I'm not sure the VS Solution is even a meaningful boundary for this discussion, since it is merely a grooping of projects, possibly one of many such "views". The source control repository is the more important issue, and not being able to commit and review changes to the different layers in a single commit would be a real impediment, and impose the unnecessary burden of coordinating changes across repos. The only exception would be if a piece of functionality is abstracted into a separate plugin, and incorrporated through a mechanism like NuGet. But those instances should be quite rare, since the "let's make this a public module" inspiration usually only happens after several implementations of a feature.

The list of specific issues in the original post makes sense. Of particular interest is how to build on top of Commerce Accelerator code, where the use of Helix boundary names can cause confusion (e.g. stating that it is okay to take a dependency on a Commerce XA "Feature", since by being Sitecore code, it is implicitly part of the "Foundation" in an implementation, as @nickwesselman proposed at the MVP Summit discussion. This raises the question of whether the use of Helix names in shipped SXA and CXA code is a good idea.)

As noted in #10, I recommend that Commerce development considerations be handled in a separate document.

[akshaysura]

Working in commerce on a high end solution, it makes 100% sense to have two solutions, not only for debugging but also for allowing multiple teams to contribute. Working in one solution does not make sense in the real world.

[nickwesselman]

@akshaysura Can you elaborate on why debugging is difficult? Seems you could start/attach to either web or commerce. And how is the multi-team scenario different w/ Commerce than any other Sitecore work?

Aren't you frequently working on features which need to touch both the Commerce engine and the front-end web experience?

[akshaysura]

@nickwesselman there are several situations when you are attached to the .net core process for the engine and also the w3p process for the XP. Having two solutions, lets you debug your functionality end to end.

If you have one solution for both, you can either/or not both.

You can categorize tasks which are commerce engine specific and XP specific and compartmentalize the development. Commerce inherently is a ton of integration work with functionality spanning both XC and XP. Based on what I have done, I cannot work on one solution.

[nickwesselman]

@akshaysura You can debug multiple processes in Visual Studio though?
https://docs.microsoft.com/en-us/visualstudio/debugger/debug-multiple-processes

By this logic shouldn't you have separate solutions for e.g. Marketing Automation as well?

[kazimnami]

@akshaysura <https://github.com/akshaysura> the guidance should be to have one repo to start with and one solution. Multiple solutions can and should be used to meet the needs of the way the team want to work but there should be one solution that exists that contains everything for new starters etc. my 2c

…

On Sat, Mar 9, 2019 at 3:17 AM Nick Wesselman ***@***.***> wrote: @akshaysura <https://github.com/akshaysura> You can debug multiple processes in Visual Studio though? https://docs.microsoft.com/en-us/visualstudio/debugger/debug-multiple-processes By this logic shouldn't you have separate solutions for e.g. Marketing Automation as well? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#11 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AOYbJEM3GGziX4iQaXJHhgaB9bhuXyAFks5vUo0PgaJpZM4UjTrz> .

[robearlam]

I agree with @kazimnami, I don't think there's anything wrong with having a sub-solutions that just contain engine projects or website projects if you and your team prefer to work in that manner. However the code should all reside in a single repository and there should be a master solution that brings them together.

If you take a look at a Product Compare module i wrote as an example: https://github.com/robearlam/Rob.Commerce/tree/master/src/Feature/ProductCompare. This has functionality that executes on both the engine and website (storefront). These pieces of functionality while deployed to different targets are tightly coupled. I believe that having two separate repos and solutions would increase the risk of changes being made to one without the other being updated. Having a single repo and master solution would reduce this risk as it forces developers to think of the system as a whole instead of just the isolated service that they happen to be working on.

[nickwesselman]

Merged @robearlam's PR finally which covers solution architecture when including Commerce, other Commerce-related inclusions should be opened as new issues.