{"_id":"5941ea4cea81b2000fbf3976","project":"55a6e72e8cc73e0d00096635","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"57e48a4000c8680e00fae6e7","version":"55a6e72f8cc73e0d00096638","__v":0,"project":"55a6e72e8cc73e0d00096635","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-09-23T01:49:52.242Z","from_sync":false,"order":3,"slug":"advanced-installation-options","title":"Advanced Installation Options"},"user":"55a6caa022cfa321008e01d6","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-15T02:00:44.727Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"This page offers version-control best practices for:\n* [Isolating Customizations for Easier Updates](#isolate)\n* [Synchronizing with Cornerstone Theme Updates](#cornerstone)\n* [Synchronizing Updates for Multiple Themes](#multiple)\n\nEach section progresses from simpler to more-complex scenarios.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Many techniques discussed below rely on GitHub's _distributed version control_ model and features. For the underlying principles, please see [Git's own documentation](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control).\",\n  \"title\": \"Distributed Version Control via Git\"\n}\n[/block]\n## <a name=\"isolate\"></a> Isolating Customizations for Easier Updates\n\nHow best to set up your customized Stencil theme to smoothly incorporate future updates in its base theme? We're gratefully sharing these guidelines from Ken Utting, Web Developer for BigCommerce client [goruck.com](https://www.goruck.com/). His scenario (slightly edited here) addresses maintaining a single custom theme that is based on a third-party Marketplace theme. But these guidelines also apply to maintaining one, or multiple, themes based on Stencil's default Cornerstone theme.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Best Practices for Handling Theme Updates\",\n  \"body\": \"We've made significant changes to our theme, and one principle that I've found successful is isolating my changes as much as possible. I try to put my changes into their own files, whether they're changes to templates, JavaScript, or SCSS. I also name all my files, CSS classes and identifiers, and JavaScript methods and classes with a `gr-` prefix (as an abbreviation for our company, GORUCK LLC). Also, any changes I make to standard theme files are identified with a comment, such as:\\n\\n    // GoRuck Customization - <reason for the customization>\\n\\nFor example, I have a file in `assets/scss/` named `gr-theme.scss`. All of the styles I've added to the theme are either in this file, or imported by this file. So for styling, my only changes to the theme itself are in a handful of places where I had to change an existing theme style (identified with a comment), plus this one line in `templates/layout/base.html`:\\n\\n    {{{stylesheet '/assets/css/gr-theme.css'}}}\\n\\nI've found that this approach provides several advantages: \\n\\n* It makes it easier to distinguish my custom code from code supplied by the default theme.\\n* It makes it less likely that my code will get intermingled with the standard theme code. This, in turn, prevents my code from unexpectedly being affected by theme updates.\\n* It makes it easier to merge base-theme updates into my theme code.\\n\\n##### <a name=\\\"parallel\\\"></a> Comparing and Merging Apples to Apples\\n\\nHaving isolated my changes as much as I can, I identify theme changes by comparing stock (base) themes, rather than by comparing base themes to my customized theme. When a new version of the theme is released, I [download the .zip file](#local-diff) from the BigCommerce control panel. I then use a desktop diff tool (Beyond Compare) to compare the new version to the .zip file of the theme's previous release. I ignore changes in the .zip file's `meta/` and `parsed/` folders, and to its `manifest.json`, and do a `Compare Contents` on the rest of the files.\\n\\nUltimately, I need to examine the changes carefully, to identify any changes that might affect, or be affected by, my customizations. And I need to test thoroughly. But comparing the stock themes to each other reduces the number of changes I have to examine. \\n\\nAlso, because I isolate my changes, most of the theme changes can be copied directly into the corresponding file in my customized theme. In practice, this means that I can limit my testing to the areas affected by changes in the standard theme, rather than having to re-test all my own changes.\\n\\nI personally find that it is also helpful to migrate *every* theme update into my customized version, as the update is released. If I were to wait, and to allow changes to accumulate and become more substantial, I think it would be more difficult to adequately test – and correctly integrate – the changes. Similarly, I'm grateful to the developer of our base theme (Pixel Union) for updates that have always made small, incremental changes.\\n\\n##### <a name=\\\"dynamic-inject\\\"></a> Dynamic Content Injection\\n\\nFinally, we've also come up with a variety of techniques for dynamically placing content on a page. For example, we can dynamically add tabs to a product page, using content stored on our WebDAV. Similarly, we can inject content from an external file into the body of a page. This allows us to put something that appears in many places, like a sizing chart, in a single place where it can be easily updated. \\n\\nOr, we can use the BigCommerce control panel's various HTML editors – for Products, Categories, and Content > Web Pages – to inject content into predefined \\\"dropzones\\\" (custom div's). This allows us to generate a wide variety of content pages using a single custom template.\\n\\nAll of these techniques move content out of the theme, minimizing the complexity of merging base-theme updates into our customized theme. For details on how we use them, please see [Dynamic Content Rendering on Stencil Storefronts](/docs/dynamic-content).\"\n}\n[/block]\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n## <a name=\"cornerstone\"></a> Synchronizing with Cornerstone Theme Updates\n\n<img style=\"float: right; margin: 0px 0px 0px 30px;\" src=\"https://files.readme.io/f25aa6c-Theme-Updates-Tree-1-Cornerstone.png\" alt=\"Two ways to sync custom themes with Cornerstone updates\" height=\"45%\" width=\"45%\" style=\"border:1px solid #D1D7E0\">\n\nThis section addresses two scenarios for keeping a custom Stencil theme synchronized with updates/enhancements to Stencil's Cornerstone base theme, or to another base theme from the BigCommerce Marketplace:\n\n* [Updating Lightly Customized Themes](#lightsync)\n* [Updating Heavily Customized Themes](#heavysync)\n\nWe've gratefully adapted these tips from Stencil developer [Dylan Staley](https://dstaley.com/)'s posting entitled [Stencil Version Control Best Practices?](https://forum.bigcommerce.com/s/question/0D51300003ejs4ACAQ/stencil-version-control-best-practices) on the [BigCommerce Community](https://forum.bigcommerce.com/s/) forums.)\n\n### <a name=\"lightsync\"></a> Updating Lightly Customized Themes\n\nIn this scenario, you can use Git's `cherry-pick` option to merge in specific Cornerstone commits. \n\n1. Use the [Stencil Framework Release Notes](/docs/release-notes) to look up specific updates' commit hashes on the [Cornerstone repository](https://github.com/bigcommerce/cornerstone).\n\n2. See [this Stack Overflow explanation](https://stackoverflow.com/questions/9339429/what-does-cherry-picking-a-commit-with-git-mean) of how to use the `cherry-pick` option.\n\n### <a name=\"heavysync\"></a> Updating Highly Customized Themes\n\nHere, unexpected errors from automatic merges can be time-consuming to undo. So, consider this handtooled approach:\n\n1. Use GitHub's Web interface to inspect each Cornerstone commit (change) of interest. Each commit will show you – for all `changed files` – a [diff view](https://help.github.com/articles/comparing-commits-across-time/) highlighting any deletions (left/red) and any insertions (right/green).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cd516df-git-diff-view-highlighted.png\",\n        \"git-diff-view-highlighted.png\",\n        1400,\n        492,\n        \"#f2f8f6\"\n      ],\n      \"caption\": \"GitHub's diff view\",\n      \"border\": false\n    }\n  ]\n}\n[/block]\n2. For changes that you want to incorporate into your theme, access the source code.\n\n    As illustrated below, you can either access individual files via Github's `Raw` view, or you can download a `.zip` of the whole Cornerstone repo in order to access all files locally.\n\n3. Manually edit the changes into your theme's affected files.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Rather than using GitHub's diff view to inspect Cornerstone changes, you are of course free to [download a Cornerstone .zip file](#local-diff) (as outlined below), then examine file changes using any desktop diff tool of your choice.\",\n  \"title\": \"Alternative Diff Tools\"\n}\n[/block]\n#### Accessing Individual Files\n\nIn the file-by-file approach: For each commit that you want to incorporate into your theme, do the following for each of the commit's `changed files`.\n\n1. In GitHub's diff view above, click the `View` button at the upper right. (We show it highlighted with a red border and a tooltip.) You will see the file's full contents, as shown below.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/041e5b1-git-raw-access.png\",\n        \"git-raw-access.png\",\n        998,\n        628,\n        \"#f6f9f9\"\n      ],\n      \"caption\": \"View a file's full contents on GitHub\",\n      \"border\": false\n    }\n  ]\n}\n[/block]\n2. Click the `Raw` button at the upper right (which we show highlighted in red). This will reveal the file's full contents as plaintext – allowing you to copy and paste without picking up the table metadata used to display line numbering.\n\n#### <a name=\"local-diff\"></a> Downloading the Whole Cornerstone Repo\n\nThis approach downloads all theme files at once, allowing you to copy/paste their relevant contents locally.\n\n1. From anywhere in the GitHub Web interface, click the Cornerstone repo's link at the upper left.\n\n    <img src=\"https://files.readme.io/1d80345-git-repo-access.png\" alt=\"Accessing the Cornerstone repo\" height=\"40%\" width=\"40%\" style=\"border:1px solid #D1D7E0\"><br>\n<span style=\"color:#888\"> Accessing the Cornerstone repo </span> <br>\n\n2. On the resulting page, open the green `Clone or download` drop-down list at the upper right, then select `Download ZIP`.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/843b648-git-download-access-highlighted.png\",\n        \"git-download-access-highlighted.png\",\n        996,\n        470,\n        \"#f4f7f7\"\n      ],\n      \"caption\": \"Downloading a .zip of the repo\",\n      \"border\": false,\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\n 3. You can then use your choice of desktop diff viewers/editors to compare and synchronize files.\n\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n## <a name=\"multiple\"></a> Synchronizing Updates for Multiple Themes\n<img style=\"float: right; margin: 0px 0px 0px 30px;\" src=\"https://files.readme.io/2e194b5-Theme-Updates-Tree-2-Multiple.png\" alt=\"Five ways to sync multiple themes' updates\" height=\"22%\" width=\"22%\" style=\"border:1px solid #D1D7E0\">\n\nThis section offers several tips for managing updates for multiple theme flavors that you or your agency might have developed for different clients: \n\n* [Enlist Your Clients in Future-Proofing](#proof)\n* [Max Out Variations](#variations)\n* [Customize Outside the Theme](#cp)\n* [Use Conditional Logic within Master Templates](#conditional)\n* [Parallel GitHub Repo's](#branch)\n\nThese tips run from simpler to more-complex scenarios, with a similar progression from simpler to more-complex tools.\n\n\n### <a name=\"proof\"></a> Enlist Your Clients in Future-Proofing\n\nWarn your clients that editing their themes' `.html` files (via [Edit Theme Files](https://support.bigcommerce.com/articles/Public/Editing-Stencil-Theme-Files)) will complicate future theme upgrades. Ask clients to keep a record of such changes, so that when you release a theme update, they can reapply their changes themselves.\n\n\n### <a name=\"variations\"></a> Max Out Variations\n\nFor very simple theme differences (like changing color values), you can maintain a different [theme variation](/docs/managing-theme-variations) per storefront or use case. Given Stencil's limit of four variations per theme, this approach obviously has limited scalability.\n\n\n### <a name=\"cp\"></a> Customize Outside the Theme\n\nRely as much as possible on dynamic aspects of the BigCommerce control panel, like the [Footer Scripts editor](https://support.bigcommerce.com/articles/Public/Adding-Custom-Scripts-to-Stencil-Themes). (Control&#8209;panel customizations are saved per store, without complicating your theme's codebase.) For other examples of control-panel options, please see [Dynamic Content Injection](#dynamic-inject) above.\n\n\n### <a name=\"conditional\"></a> Use Conditional Logic within Master Templates\n\nFor subtle changes to a portion of a template file, use [Handlebars helpers](/docs/developing-with-handlebars) and [conditionals](/docs/stencil-technology-base#Syntax) to render different HTML for each client's flavor of the theme.\n\n\n### <a name=\"branch\"></a> Parallel GitHub Repo's\n\nWhere different clients' theme flavors diverge into completely custom pages – for example, each client has a wildly different homepage layout – Git's systematic version control helps. You will probably want to fork or branch separate repo's, one per client, and maintain/update them in parallel.\n\nAs with relying on theme [variations](#variations), this approach has limited scalability. Beyond a certain number of clients/themes (certainly by 10), it becomes cumbersome.\n\n#### Buffered Updates to Multiple Themes\n\nFor greater scalability, you might choose to create your own master fork/branch of Cornerstone for your group of themes. Keep that fork/branch in sync with Cornerstone updates, then cascade the updates to theme-specific repo's that you fork/branch from this master. (This extends the approach of [isolating customizations](#isolate), outlined above.)","excerpt":"","slug":"theme-updates-sync","type":"basic","title":"Theme Updates and Version Control"}

Theme Updates and Version Control


This page offers version-control best practices for: * [Isolating Customizations for Easier Updates](#isolate) * [Synchronizing with Cornerstone Theme Updates](#cornerstone) * [Synchronizing Updates for Multiple Themes](#multiple) Each section progresses from simpler to more-complex scenarios. [block:callout] { "type": "info", "body": "Many techniques discussed below rely on GitHub's _distributed version control_ model and features. For the underlying principles, please see [Git's own documentation](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control).", "title": "Distributed Version Control via Git" } [/block] ## <a name="isolate"></a> Isolating Customizations for Easier Updates How best to set up your customized Stencil theme to smoothly incorporate future updates in its base theme? We're gratefully sharing these guidelines from Ken Utting, Web Developer for BigCommerce client [goruck.com](https://www.goruck.com/). His scenario (slightly edited here) addresses maintaining a single custom theme that is based on a third-party Marketplace theme. But these guidelines also apply to maintaining one, or multiple, themes based on Stencil's default Cornerstone theme. [block:callout] { "type": "info", "title": "Best Practices for Handling Theme Updates", "body": "We've made significant changes to our theme, and one principle that I've found successful is isolating my changes as much as possible. I try to put my changes into their own files, whether they're changes to templates, JavaScript, or SCSS. I also name all my files, CSS classes and identifiers, and JavaScript methods and classes with a `gr-` prefix (as an abbreviation for our company, GORUCK LLC). Also, any changes I make to standard theme files are identified with a comment, such as:\n\n // GoRuck Customization - <reason for the customization>\n\nFor example, I have a file in `assets/scss/` named `gr-theme.scss`. All of the styles I've added to the theme are either in this file, or imported by this file. So for styling, my only changes to the theme itself are in a handful of places where I had to change an existing theme style (identified with a comment), plus this one line in `templates/layout/base.html`:\n\n {{{stylesheet '/assets/css/gr-theme.css'}}}\n\nI've found that this approach provides several advantages: \n\n* It makes it easier to distinguish my custom code from code supplied by the default theme.\n* It makes it less likely that my code will get intermingled with the standard theme code. This, in turn, prevents my code from unexpectedly being affected by theme updates.\n* It makes it easier to merge base-theme updates into my theme code.\n\n##### <a name=\"parallel\"></a> Comparing and Merging Apples to Apples\n\nHaving isolated my changes as much as I can, I identify theme changes by comparing stock (base) themes, rather than by comparing base themes to my customized theme. When a new version of the theme is released, I [download the .zip file](#local-diff) from the BigCommerce control panel. I then use a desktop diff tool (Beyond Compare) to compare the new version to the .zip file of the theme's previous release. I ignore changes in the .zip file's `meta/` and `parsed/` folders, and to its `manifest.json`, and do a `Compare Contents` on the rest of the files.\n\nUltimately, I need to examine the changes carefully, to identify any changes that might affect, or be affected by, my customizations. And I need to test thoroughly. But comparing the stock themes to each other reduces the number of changes I have to examine. \n\nAlso, because I isolate my changes, most of the theme changes can be copied directly into the corresponding file in my customized theme. In practice, this means that I can limit my testing to the areas affected by changes in the standard theme, rather than having to re-test all my own changes.\n\nI personally find that it is also helpful to migrate *every* theme update into my customized version, as the update is released. If I were to wait, and to allow changes to accumulate and become more substantial, I think it would be more difficult to adequately test – and correctly integrate – the changes. Similarly, I'm grateful to the developer of our base theme (Pixel Union) for updates that have always made small, incremental changes.\n\n##### <a name=\"dynamic-inject\"></a> Dynamic Content Injection\n\nFinally, we've also come up with a variety of techniques for dynamically placing content on a page. For example, we can dynamically add tabs to a product page, using content stored on our WebDAV. Similarly, we can inject content from an external file into the body of a page. This allows us to put something that appears in many places, like a sizing chart, in a single place where it can be easily updated. \n\nOr, we can use the BigCommerce control panel's various HTML editors – for Products, Categories, and Content > Web Pages – to inject content into predefined \"dropzones\" (custom div's). This allows us to generate a wide variety of content pages using a single custom template.\n\nAll of these techniques move content out of the theme, minimizing the complexity of merging base-theme updates into our customized theme. For details on how we use them, please see [Dynamic Content Rendering on Stencil Storefronts](/docs/dynamic-content)." } [/block] <hr style="background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;"/> ## <a name="cornerstone"></a> Synchronizing with Cornerstone Theme Updates <img style="float: right; margin: 0px 0px 0px 30px;" src="https://files.readme.io/f25aa6c-Theme-Updates-Tree-1-Cornerstone.png" alt="Two ways to sync custom themes with Cornerstone updates" height="45%" width="45%" style="border:1px solid #D1D7E0"> This section addresses two scenarios for keeping a custom Stencil theme synchronized with updates/enhancements to Stencil's Cornerstone base theme, or to another base theme from the BigCommerce Marketplace: * [Updating Lightly Customized Themes](#lightsync) * [Updating Heavily Customized Themes](#heavysync) We've gratefully adapted these tips from Stencil developer [Dylan Staley](https://dstaley.com/)'s posting entitled [Stencil Version Control Best Practices?](https://forum.bigcommerce.com/s/question/0D51300003ejs4ACAQ/stencil-version-control-best-practices) on the [BigCommerce Community](https://forum.bigcommerce.com/s/) forums.) ### <a name="lightsync"></a> Updating Lightly Customized Themes In this scenario, you can use Git's `cherry-pick` option to merge in specific Cornerstone commits. 1. Use the [Stencil Framework Release Notes](/docs/release-notes) to look up specific updates' commit hashes on the [Cornerstone repository](https://github.com/bigcommerce/cornerstone). 2. See [this Stack Overflow explanation](https://stackoverflow.com/questions/9339429/what-does-cherry-picking-a-commit-with-git-mean) of how to use the `cherry-pick` option. ### <a name="heavysync"></a> Updating Highly Customized Themes Here, unexpected errors from automatic merges can be time-consuming to undo. So, consider this handtooled approach: 1. Use GitHub's Web interface to inspect each Cornerstone commit (change) of interest. Each commit will show you – for all `changed files` – a [diff view](https://help.github.com/articles/comparing-commits-across-time/) highlighting any deletions (left/red) and any insertions (right/green). [block:image] { "images": [ { "image": [ "https://files.readme.io/cd516df-git-diff-view-highlighted.png", "git-diff-view-highlighted.png", 1400, 492, "#f2f8f6" ], "caption": "GitHub's diff view", "border": false } ] } [/block] 2. For changes that you want to incorporate into your theme, access the source code. As illustrated below, you can either access individual files via Github's `Raw` view, or you can download a `.zip` of the whole Cornerstone repo in order to access all files locally. 3. Manually edit the changes into your theme's affected files. [block:callout] { "type": "success", "body": "Rather than using GitHub's diff view to inspect Cornerstone changes, you are of course free to [download a Cornerstone .zip file](#local-diff) (as outlined below), then examine file changes using any desktop diff tool of your choice.", "title": "Alternative Diff Tools" } [/block] #### Accessing Individual Files In the file-by-file approach: For each commit that you want to incorporate into your theme, do the following for each of the commit's `changed files`. 1. In GitHub's diff view above, click the `View` button at the upper right. (We show it highlighted with a red border and a tooltip.) You will see the file's full contents, as shown below. [block:image] { "images": [ { "image": [ "https://files.readme.io/041e5b1-git-raw-access.png", "git-raw-access.png", 998, 628, "#f6f9f9" ], "caption": "View a file's full contents on GitHub", "border": false } ] } [/block] 2. Click the `Raw` button at the upper right (which we show highlighted in red). This will reveal the file's full contents as plaintext – allowing you to copy and paste without picking up the table metadata used to display line numbering. #### <a name="local-diff"></a> Downloading the Whole Cornerstone Repo This approach downloads all theme files at once, allowing you to copy/paste their relevant contents locally. 1. From anywhere in the GitHub Web interface, click the Cornerstone repo's link at the upper left. <img src="https://files.readme.io/1d80345-git-repo-access.png" alt="Accessing the Cornerstone repo" height="40%" width="40%" style="border:1px solid #D1D7E0"><br> <span style="color:#888"> Accessing the Cornerstone repo </span> <br> 2. On the resulting page, open the green `Clone or download` drop-down list at the upper right, then select `Download ZIP`. [block:image] { "images": [ { "image": [ "https://files.readme.io/843b648-git-download-access-highlighted.png", "git-download-access-highlighted.png", 996, 470, "#f4f7f7" ], "caption": "Downloading a .zip of the repo", "border": false, "sizing": "smart" } ] } [/block] 3. You can then use your choice of desktop diff viewers/editors to compare and synchronize files. <hr style="background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;"/> ## <a name="multiple"></a> Synchronizing Updates for Multiple Themes <img style="float: right; margin: 0px 0px 0px 30px;" src="https://files.readme.io/2e194b5-Theme-Updates-Tree-2-Multiple.png" alt="Five ways to sync multiple themes' updates" height="22%" width="22%" style="border:1px solid #D1D7E0"> This section offers several tips for managing updates for multiple theme flavors that you or your agency might have developed for different clients: * [Enlist Your Clients in Future-Proofing](#proof) * [Max Out Variations](#variations) * [Customize Outside the Theme](#cp) * [Use Conditional Logic within Master Templates](#conditional) * [Parallel GitHub Repo's](#branch) These tips run from simpler to more-complex scenarios, with a similar progression from simpler to more-complex tools. ### <a name="proof"></a> Enlist Your Clients in Future-Proofing Warn your clients that editing their themes' `.html` files (via [Edit Theme Files](https://support.bigcommerce.com/articles/Public/Editing-Stencil-Theme-Files)) will complicate future theme upgrades. Ask clients to keep a record of such changes, so that when you release a theme update, they can reapply their changes themselves. ### <a name="variations"></a> Max Out Variations For very simple theme differences (like changing color values), you can maintain a different [theme variation](/docs/managing-theme-variations) per storefront or use case. Given Stencil's limit of four variations per theme, this approach obviously has limited scalability. ### <a name="cp"></a> Customize Outside the Theme Rely as much as possible on dynamic aspects of the BigCommerce control panel, like the [Footer Scripts editor](https://support.bigcommerce.com/articles/Public/Adding-Custom-Scripts-to-Stencil-Themes). (Control&#8209;panel customizations are saved per store, without complicating your theme's codebase.) For other examples of control-panel options, please see [Dynamic Content Injection](#dynamic-inject) above. ### <a name="conditional"></a> Use Conditional Logic within Master Templates For subtle changes to a portion of a template file, use [Handlebars helpers](/docs/developing-with-handlebars) and [conditionals](/docs/stencil-technology-base#Syntax) to render different HTML for each client's flavor of the theme. ### <a name="branch"></a> Parallel GitHub Repo's Where different clients' theme flavors diverge into completely custom pages – for example, each client has a wildly different homepage layout – Git's systematic version control helps. You will probably want to fork or branch separate repo's, one per client, and maintain/update them in parallel. As with relying on theme [variations](#variations), this approach has limited scalability. Beyond a certain number of clients/themes (certainly by 10), it becomes cumbersome. #### Buffered Updates to Multiple Themes For greater scalability, you might choose to create your own master fork/branch of Cornerstone for your group of themes. Keep that fork/branch in sync with Cornerstone updates, then cascade the updates to theme-specific repo's that you fork/branch from this master. (This extends the approach of [isolating customizations](#isolate), outlined above.)