UPDATE: A few additional remarks on the semver question below.
I have been working with @tfthacker on a small functional update for tfthacker/obsidian42-brat which adds the following:
- Instead of depending on the
manifest-beta.jsonfile, it will read release info from the GitHub (See the1.0.7-preview.1for details), and will update to the latest published (pre-)release according to the hierarchy of semantic versions (see below) - It also implements a “version” dropdown when adding a frozen version, also populated by the published GitHub (pre-)releases
- It lets a user manually change the version of a plugin installed as a “frozen version”
Figure 1: Trying to add a frozen version for a valid plugin repository
Figure 2: Trying to add a frozen version for an inexistent plugin
Figure 3: Change frozen version with the “Edit” button
Would be very happy to have Plugin Dev’s feedback (and maybe testing). BRAT can bootstrap itself into this pre-prelease existence if you add tfthacker/obsidian42-brat as a frozen version 1.0.7-preview.1, and reload the plugin.
Changes with respect to using manifest-beta.json
By using the github releases instead of manifest-beta.json the plugin will:
- download a specific frozen version if specified (independently of whether it is defined as “pre-release” or not), or
- download the latest version available as a release or pre-releasae, giving priority to the highest version number according to the semantic version rules (see below)
Specifically, it will fetch the manifest.json from the latest (or specified) (pre-)release package in the repository to install and update a plugin.
This makes BRAT independent of the version numbering in the repository root, and also allows developers to use semantic-release and beta branches to develop pre-releases that all work with BRAT.
For plugin devs, this means that manifest-beta.json is not strictly necessary anymore, although having it in a repository doesn’t hurt at all and will keep your beta version backwards compatible with older BRAT versions.
As far as I understand, Obsidian and plugins like the Obsidian plugin tracker currently look at the master manifest.json in the default branch of a plugin repository when updating plugins, which is also compatible with this change. If a developer releases a “beta” version as an independent, but “full” release in his repository (e.g. without updating the manifest.json in the repository), BRAT will also pick it up independently of the version number in the master mainfest.json of the repository.
It will also make BRAT more robust, as it will always use the true release list as its source of truth.
Finally, it will work nicely with semantic-release in general and @brianrodri’s brianrodri/semantic-release-obsidian-plugin in particular: any successful build of a (pre-)release (beta and similar) will be picked-up by the plugin automatically.
To make a concrete example: If you add an alpha, beta and preview branch, the highest preview version would be preferred over beta or alphaversions, ensuring people using the plugin without frozen versions will get the most stable pre-release (and highest release, if available). By using semantic-release, you can very much automate the whole process of early preview releases without polluting the normal releases, and this update to BRAT will make this work nicely for users who want to test alpha/beta/preview releases made available by a dev.
| Semantic Versions | |
|---|---|
| The results of a Semver comparison from lowest to highest version | |
| 1.0.0 | 1 |
| 1.0.1-alpha.25 | 2 |
| 1.0.1-beta.5 | 3 |
| 1.0.1-preview.1 | 4 |
| 1.0.1 | 5 |
Also note that there is a difference in how Obsidian processes and uses version numbers: Althoug the reference is to Semantic Versioning, Obsidian only supports a subset. Versions can “only use numbers and periods (.)”. Obsidian itself will not therefore not take care of pre-releases, but BRAT will do so and update according to the full semantic version logic. This means that once a regular version is released on the main branch, Obsidian will not automatically upgrade from an installed pre-release.
In our example above, that would mean that if a user has used BRAT to install any of the -alpha.x, -beta.y or -preview.z (pre-release) versions, they need to manually update (via BRAT or otherwise) once 1.0.1 is released, as Obsidian’s version check will not pick it up over the pre-releases. However, once the version number of the release is higher than the previous version (e.g. once 1.0.2 is released), Obsidian will pick this up as a version bump over both the 1.0.1 release and any 1.0.1-branch.x pre-release.
If you use BRAT to install and manage upgrades to plugins it tracks, this should be no issue for you.