Managing nopCommerce plugins with git submodule

In this article I’m going to demonstrate the way we have found works best for us when managing the same nopCommerce plugin in several projects. When we started out doing nopCommerce and plugin development around 2012, we began by creating one plugin for one project. This plugin was then copied over to the next project and then the next project and so on. When each project also needed its own little tweak of the plugin functionality it quickly became very hard to keep all the plugins up to date with each other, and it’s a very time consuming daunting task. Also it takes away time from creating business value.

Today we are managing our plugins with help of git submodules. Each nopCommerce installation has its own git repository, each of our own plugins inside of the repository has its own git repository, i.e. nested git repositories or submodules. When we make a change inside a plugin we push that change to the plugins own repository and can easily distribute the change to all other project by simply updating the project's submodules.

Add a plugin as a submodule

We have a plugin with following root structure:

One folder for the actual plugin and one folder containing unit tests that are testing the plugin.

Now we want to install this plugins inside of our nopCommerce project.

In the root of the nopCommerce project add the submodule by following command:

git submodule add https://github.com/<user>/nopcommerce-fortnox src/Majako.Plugin.Misc.Fortnox

This will place the submodule inside src/Majako.Plugin.Misc.Fortnox. Out of the box the nopCommerce plugins are placed inside the Plugins folder. We could have followed this convention but it would make our plugin folder structure one directory deeper and we would need to change the plugins references file paths. It would still work perfectly fine but this way we don’t need different file paths for our own plugins.

Git will also place a new file in the root folder called .gitmodules containing configuration for all added submodules.

Next step is to add the plugin and the test project to the solution inside Visual Studio by simply right click the Plugins folder and choose Add existing project..., locate the plugins .csproj file and add it, if you have a test project add that too.

The solution should now look something like this

Commit and push changes in the submodule

Now let’s say you have made some changes to the plugin, we need to commit the changes to the plugins repository and also update the nopCommerce git repository to reference to the latest commit in the submodule.

Inside the plugins git repository commit and push the changes

git add -A
git commit -m "New neat feature"
git push origin master

The changes are now pushed to the git repository. If going back to the nopCommerce root directory and typing git status you will see there is also a pending change here, something like:

modified:   src/Majako.Plugin.Misc.Fortnox (new commits, modified content)

Indicating that a new commit of the submodule is referenced. This change will also need to be commited.

Update the plugin in another project

Now when all changes are committed and pushed, it’s time to reap the benefits of working with submodules by updating the plugin changes in another nopCommerce project where the very same plugin is added.

Inside the other nopCommerce projects root enter

 git submodule update --recursive --remote

This will update all the submodules. We are now in sync between the two different projects.

Working with different versions of the plugin

Let’s say the plugin needs to be compatible with more than one version of nopCommerce. Git submodules doesn’t work well with release tags, instead we are handling this by creating a branch for each nopCommerce version in the plugins.

For example in the plugin we have two different version branches:

Where first part of the branch name is the nopCommerce version, and the second part is the version of the plugin, following semver. With this branching structure we can easily create a new bug-, feature- or (god forbidd ;)) breaking release of the plugin for a specific nopCommerce version by bumping the plugins version name.

For example let’s say in the v4.1 version of the plugin we fixed a bug, we can release this fix by creating a new branch called v4.1-1.0.1. If the same bug fix would also be corrected in the v4.0 version we could do the same here v4.0-1.0.1.

You can point the submodule to a specific branch by modifying the .gitmodule:

[submodule "src/Majako.Plugin.Misc.Fortnox"]
    path = src/Majako.Plugin.Misc.Fortnox
    url = https://github.com/<user>/nopcommerce-fortnox.git
    branch = v4.1-1.0.0

To update to this branch enter

git submodule update --remote

Summary

This is how we currently are managing plugins and versioning across multiple projects. We are always looking to improve our workflow in order to create better and faster software all the time. I would love to hear what your thoughts are, how you are managing plugins or if you have any thoughts how we could improve our workflow. Please comment below.

Happy nopCommerce coding!
Martin