Versioning for your Ghost theme is probably not something you’ve given much attention but it’s an important part of the process for maintaining a Ghost site.
Using consistent versioning in your Ghost theme allows you to make continuous improvements to your site’s look and feel, knowing that you can easily revert your changes if something goes wrong.
Here’s how to correctly use versioning in your Ghost theme.
RELATED: Customizing a Ghost theme
Using Semantic Versioning for your Ghost Theme
You’re probably familiar with semantic versions even if you’ve never run across the term before.
Semantic versions are actually three versions separated by periods (‘.’) where each of the versions has a specific meaning. Take for instance the semantic version: 1.2.3
The number one (‘1’) is known as the major version. ‘2’ is the minor version. ‘3’ is the point version.
You start with a base version – like 0.0.0 or 1.0.0 – and then increase the version with each change. How you increment the version is fairly subjective but generally falls within some broad guidelines.
Update the major number for only the most significant changes
The major number changes for really significant redesigns of your theme. If you start with a theme and only make incremental changes you may never increase your major version.
For mindspun.com we’ve bumped the version number a handful of times for the reasons such as:
- The build system for the theme changed.
- We moved from Bootstrap 4.x to Bootstrap 5.
- The site navigation was re-designed.
It’s really up to you if a change is significant enough to warrant increasing the major version number.
Always bump the major version if introducing a breaking change.
The one time you should always increase the version number is if you are introducing a breaking change. In other words, if your change may break something for the user because the new theme is no longer compatible, then definitely increase the major version number.
Update the minor number for incremental features
Increase the minor number when you add new features to your theme.
Examples include:
- New or changed page templates.
- Updates to the theme to support new versions of Ghost.
- Add a new component or widget.
The general rule for minor version changes is that if you are adding a new feature then update the minor version.
Update the minor version for new features.
There is no ‘maximum’ minor version number and it’s very common to have high minor version numbers whereas the major version is generally small – e.g. 2.42.0
Update the point version for bug fixes
The point release is used to indicate a bug fix. The most common example: typos.
Update the point version for bug fixes.
A new version that fixes something in your Ghost theme but doesn’t add a new feature or other functionality should be a point release.
Building your Ghost Theme
Once you have a versioning scheme, your Ghost theme needs to make use of it. Fortunately, most existing themes will already do this, so there are plenty of examples available.
The version number should be updated in only one place: package.json. One of the JSON attributes is named version.
If updating your theme version requires changes in multiple places, it increases the chance of error.
To put it another way, you’ll soon mess it up. For one of our themes, we originally had the version in two places: package.json and the Readme.md file (for a github badge) – it only took a handful of updates before we forgot to update the Readme.
Use the version in the filename of your Ghost theme.
The filename for your Ghost theme zip file should contain the version number. In other words, theme-1.2.3.zip should be used instead of just theme.zip.
Using the version number in the filename prevents Ghost from overwriting your previous theme version, while still retaining the same theme name. When you publish a new version of your theme, you always want the previous version of a theme to be available in the Ghost admin interface so that you can revert to it quickly by clicking ‘ACTIVATE’. No waiting for you to dig up the old version and re-upload it – that process always takes longer than your think.
The spin theme automatically appends the version number from package.json in the ‘zip’ gulp task.
Publish your Ghost Theme
Once you have a correctly versioned and built theme the final step is publish it to your site – or release it to your customers to publish to their site.
Publish it as your normally would – using the Ghost admin interface under branding.
The best practice is to keep sufficient versions so that you can always go back to a working version if an issue is found. Keep all versions for the current and previous major release. In practice, it’s probably easy enough just to keep all previous versions.
Mailing Address