Obsidian Plugin: `semantic-release` boilerplate config

.releaserc.yaml

# Boilerplate semantic-release configuration for an Obsidian plugin
# run semantic-release as follows to release a new version of your plugin:
#   dry-run (default):  npx -p github:brianrodri/semantic-release-obsidian-plugin semantic-release 
#   for real: npx -p github:brianrodri/semantic-release-obsidian-plugin semantic-release --dry-run false
# If `package.json` has a `repository` key configured, but you want to work on, say, a fork or development version on your own 
# repository / user, you might have to specify the `repositoryUrl`:
# - either as a command-line argument (e.g. -r <url>) or by uncommenting and modifying the following line:
# repositoryUrl: https://github.com/<user>/<repository> 
branches:
  - main
  - master
  - beta
  - name: 'a-test-branch'
    prerelease: true
plugins:
  - "@semantic-release/commit-analyzer"
  - "@semantic-release/release-notes-generator"
  - semantic-release-obsidian-plugin
  - - "@semantic-release/github"
    - assets:
        - path: main.js
        - path: manifest.json # semantic-release-obsidian-plugin will update the file in the root
        - path: styles.css
# Use the following of you build into a sub-directory
#    - assets:
#        - path: dist/main.js
#        - path: manifest.json # semantic-release-obsidian-plugin will update the file in the root
#        - path: dist/styles.css 
tagFormat: "${version}"
ci: false
dryRun: true

README.md

Using semantic-release for your Obsidian plugin and development forks alike

The brianrodri/semantic-release-obsidian-plugin allows the use of semantic-release for Obsidian plugins. The .releaserc.yaml file in this Gist contains a boilerplate configuration that allows you to instantly use the semantic-release package to release pre-release and release versions of your plugins or plugin forks, without polluting the package.json, and without the need to set-up a workflow on GitHub.

How to use

Copy the file .releaserc.yaml to your plugin root directory, make necessary adjustments (build path and branches to use as pre-release), and set up the GITHUB_TOKEN or GH_TOKEN environment variable according to the documentation. Depending on the plugin you are working on, you might have to specify the repositoryUrl of your own repository.

Build your plugin (if you use the obsidian-plugin-template, it's usually npm run build) and then dry-run semantic-release to check everything is correctly in place:

npx -p github:brianrodri/semantic-release-obsidian-plugin semantic-release --dry-run

(This will both verify whether you can push to GitHub, and show you what version and which changes would be contained in that file)

Publish a new semantic version:

npx -p github:brianrodri/semantic-release-obsidian-plugin semantic-release --dry-run false

The configuration deliberately sets dryRun: true so you don't inadvertently publish a new version when running semantic-release in a repository. Feel free to change this.

Please have a look at the configuration documentation for more details.

How to use together with BRAT

BRAT is a plugin for Obsidian that allows you to load any plugin directly from it's Github release. Although BRAT currently depends on a manifest[-beta].json to load (beta-)versions, it can be used for pre-releases published with semantic-release by adding the plugin to BRAT using "Add Beta plugin with frozen version" and specifying the version number you just published.

E.g. if your plugin is user/obsidian-fabulous-plugin and the pre-release version is 1.0.0-beta.1, you would specify this as your version number:

Caution

Manually tracking (pre-release) versions in BRAT is a bit tedious as you have to remove and manually add each new (pre-)release as a new frozen version. If you feel adventerous, you can switch to a pre-release version of BRAT from a fork I wrote that will load the latest published release or pre-release (whichever is higher) based on the GitHub releases and tags created by semantic-release (and not based on the information in the manifest[-beta].json). You find it here¹:

• Add this modified BRAT plugin by using "Add Beta plugin with frozen version" with the following info: johannrichard/obsidian42-brat: 1.0.0-use-github-releases.1 (or whatever latest pre-release is published in my repository at that time). This will then bootstrap the enhanced BRAT version into Obsidian.
• Then, remove the plugin in the BRAT config (but don't delete it) and add johannrichard/obsidian42-brat back as a beta plugin without specific version. This will then (re)load the latest published release or pre-release from my repository.

This way you will get any updated beta versions of the fork that I might publish until a newer version than my beta/fork is published at https://github.com/TfTHacker/obsidian42-brat.

If you run into any problems with that fork, you can simply revert BRAT to it's official release. You can do this either by re-installing BRAT from the Obsidian Community Plugin list or using modified BRAT to reinstall unmodified BRAT by deleting johannrichard/obsidian42-brat and adding TfTHacker/obsidian42-brat instead.

How to make sure (your) old versions are used as baseline by semantic-release?

Have a look at Existing Version Tags. This also works for forks: if you add an (empty) release with the current version number of the plugin to your releases, semantic-release will use that as the baseline. Normally, if a higher version number than the (beta) on your fork or the upstream repository is released, then Obsidian will pick up that newer version and propose as an update.

Caveats

• brianrodri/semantic-release-obsidian-plugin will update the version numbers in the manifest.json file in the root folder of your repository. You should therefore leave the github release line for asset. manifest.json as is, even if your build script copies manifest.json to the build directory: the build happens before semantic-release is run and will therefore copy the file with the wrong version number
• Running semantic-release this way will modify version numbers in all relevant files (mainfest.json, versions.json, and package[-lock].json), but it won't commit them. Since the correct next version number is always deduced from the latest tags in the repository, you can simply revert these changes, unless you intend to publish a new major / minor release on the ?master or main (default) branch: in that case, the manifest.json and versions.json must be updated so that Obsidian will pick up the updated version.
• While @semantic-release/git can be used to commit these files when releasing a new version, the semantic-release/git maintainers strongly recommend against making commits during your release.
• Other methods to bump the version number (e.g. a versions-bump.mjs in the default template) are not needed anymore if you publish with semantic-release

Footnotes

1. I have proposed PR #93 to the author of BRAT which would integrate this into the official plugin. ↩