Versioning
bulletinbored uses semantic versioning (SemVer): MAJOR.MINOR.PATCH. The current version is 1.0.0.
The project is released under the BSD Zero Clause (BSD-0). See LICENSE and CLA.md.
What the numbers mean
MAJOR— incremented for incompatible changes that require migration (e.g. config key renames, database schema breaks)MINOR— incremented for new features that are backward-compatible (e.g. new admin panels, new core hooks, new managers)PATCH— incremented for bug fixes and security patches that don’t add features
The 1.0 API is stable. Incompatible changes require a major release, so a 1.x minor or patch release is backward-compatible.
Prereleases
Prereleases use a SemVer suffix such as 1.0.0-rc.1 or 1.0.0-beta.2. Build metadata alone (1.0.0+build.5) does not make a version a prerelease.
- Prerelease updates are opt-in. Set
allow_prerelease_updatestotrueinconfig.jsonto be offered them. A stable installation never receives a prerelease unless this key is enabled; an installation already running a prerelease may follow the next prerelease. - GitHub’s
/releases/latestendpoint skips prereleases, so a GitHub-backed update check only sees stable releases unless the installation already follows prereleases. bb_version_is_prerelease()andbb_version_base()inlib/Version.phpimplement the checks. SeeUpdateManager::isUpdateAllowed()inlib/UpdateManager.phpfor the offer rules.- Extension
coreconstraints are matched against the base version: a plugin declaring"core": ">=1.0.0"is installable on1.0.0-rc.1because the suffix is stripped for requirement matching (lib/PluginManager/PluginManifest.php). Update comparisons keep the full version, so1.0.0-rc.1ranks below1.0.0.
How to bump a version
Edit the
VERSIONfile at the project root (single line, e.g.1.0.0)Update the version in
config-sample.jsonso it matchesVERSION.VersionConsistencyTestasserts thatVERSION,config-sample.jsonand the release notes agree.If you ship updates via the Update Manager, make sure
versions.jsonon your update mirror exposes the new version.Tag the release in git:
git add VERSION git commit -m "Bump version to 1.0.0" git tag 1.0.0 git push --follow-tagsTags may carry an optional
vprefix (v1.0.0); the release workflow and the updater normalize it before comparing.
Where the version lives in code
VERSION: single-source-of-truth file at the project rootconfig.json:versionis read fromconfig.jsonat boot (src/bootstrap.php); the installer and the updater write it fromVERSION(install3.php,lib/UpdateManager.php)data/updates.json: stores installed versions for core, plugins, and themes
Version checks
The Update Manager compares installed versions with remote versions:
- Core version comes from
config['version'] - Folder plugins declare their version in
manifest.json(lib/PluginDiscovery.php). Legacy single-file plugins fall back to aVersion:header. - Theme versions come from
manifest.jsonin each theme folder
versions.json is fetched from the configured update_mirror. update_server, when it points at a GitHub repository, is the fallback source and uses the GitHub Releases API, so no versions.json is required for that path (lib/UpdateFetcher.php).
Example release checklist
- Update
VERSIONfile andconfig-sample.json - Update changelog / docs
- Run the test suite (
php tests/run.php), includingtests/ReleasePackageTest.php - Commit and tag, then let
.github/workflows/release.ymlbuild and publish the package - Build the distribution archive locally if needed with
php tools/build-release.php. The builder produces only the core archive; plugin and theme packages are separate. - Update remote
versions.jsonon the update mirror pointing to the new packages (only for non-GitHub update servers)