While developing my new theme I could not find much guidance for beginners on how to set up a release process, so I have come up with my own. In case it is of help to fellow amateur theme developers, I’ve outlined what I did below.
what I wanted to do was:
- automatically create github releases based on changes since the previously published release
- automatically deploy any pushed commits to my personal blog
- automatically deploy any published versions to my theme demo site.
The out-of-the-box Ghost github integration makes it simple to solve 2 and 3, you just need to configure two workflows, per the instructions.
Solving part I involved a bit more work:
picking a build tool and package management tool
as a novice node/javascript developer, I found the whole topic of js build tools and package managers utterly bewildering. There are too many choices! so I just stuck with gulp and npm respectively, which is how it is done in some of the standard Ghost themes.
The gulp configuration is used to do a few things:
- concatenation and minification of css/js files
- creation of a zip file containing all the theme assets needed to install the theme
- running a file watcher that automatically updates the files in the
builtdirectory as you make changes to the theme code
npm is used for two things
- managing the node package dependencies defined in package.json
- combing various steps in the release process into single commands (more on this below)
manage github releases
I had to create a new javascript to handle the publication of changes to github. It doesn’t have any dependencies and uses the standard github REST API.
configuring release commands
npm scripts are a nice simple way to organise multiple bash commands that can all be neatly contained in the package.json. This is what I have in my configuration
"scripts": {
"dev": "gulp dev",
"zip": "gulp zip",
"test": "gscan .",
"bump-patch": "npm version patch --message 'bump patch version to %s' && git push origin main",
"bump-minor": "npm version minor --message 'bump minor version to %s' && git push origin main",
"bump-major": "npm version major --message 'bump major version to %s' && git push origin main",
"create-changelog": "./release --create-changelog",
"create-release": "./release --create-release published",
"create-draft-release": "./release --create-release draft",
"upload-zipfile": "./release --upload-zipfile dist/transmission.zip",
"full-release": "gscan . && ./release --create-changelog && ./release --create-release published && gulp zip && ./release --upload-zipfile dist/transmission.zip ",
"draft-full-release": "gscan . && ./release --create-changelog && ./release --create-release draft"
}
so creating a new release is a simple as
# increments the package.json version and pushes to the github repo.
npm run bump-minor # (or bump-patch/bump-major)
npm run full-release # gscan, create changelog, publish release on github
you can run the individual steps like npm create-changelog separately if you prefer (this will give you an opportunity to change the release message before publishing the release.
hope that helps someone else!
If I have reinvented the wheel, please don’t worry about hurting my feelings if you let me know :)
).