BetterDesk/docs/important/branching-and-versioning.md

Branching and versioning

BetterDesk uses two Git branches and automated product versioning across the repository.

Branches

Branch	Role	Version bump	GitHub Release
dev	Active development; default target for pull requests	+0.0.1 on every push (CI commit [version-bump])	No — Docker images tagged dev / sha-* on GHCR
main	Stable production; stricter review and PRE_RELEASE_CHECKLIST.md	+0.1.0 when a PR is merged into main	Yes — tag vX.Y.Z, GitHub Release, server binaries, semver Docker tags

Typical flow

1. Feature branches merge into dev (patch version auto-increments).
2. When ready for production, open a PR dev → main and complete the release checklist.
3. On merge, CI bumps minor version, tags, and publishes a release.
4. Merge main → dev so development continues from the new minor baseline (e.g. 3.1.0 → next dev commits 3.1.1, 3.1.2, …).

gitGraph
   commit id: "3.0.0"
   branch dev
   checkout dev
   commit id: "3.0.1"
   commit id: "3.0.2"
   checkout main
   merge dev id: "3.1.0 release"
   checkout dev
   merge main id: "sync 3.1.0"
   commit id: "3.1.1"

Product version files (Tier 1 + 2)

Canonical version: root VERSION file.

Every automated bump updates these together:

Tier 1

• VERSION
• web-nodejs/package.json (npm mirror; panel reads root VERSION via web-nodejs/lib/productVersion.js)
• betterdesk-server/VERSION and betterdesk-server/internal/productversion/VERSION (Go go:embed + builds)
• betterdesk.sh, betterdesk.ps1, betterdesk-docker.sh
• CHANGELOG.md (moves [Unreleased] → new section)
• README.md (version badge)

Tier 2 (Docker)

• Dockerfile, Dockerfile.server, Dockerfile.console
• docker-compose.quick.yml, docker-compose.quick.macvlan.yml
• docker/entrypoint.sh, docker-entrypoint.sh

The web console and Go server should report the same product semver after a normal install, panel update, or release build. Settings → Server Information shows both the product version and the live Go server version from /api/health.

Sub-project versions (betterdesk-mgmt, betterdesk-agent-client, SDKs) are not bumped with the main product unless explicitly requested.

Maintainer commands

# Verify all Tier 1/2 files match VERSION (CI runs this too)
node scripts/bump-version.js --verify

# List every path touched by automated bumps (used by CI git add)
node scripts/bump-version.js --list-paths

# Manual bump (normally CI handles this)
node scripts/bump-version.js --patch    # +0.0.1
node scripts/bump-version.js --minor    # +0.1.0
node scripts/bump-version.js --set 3.2.0
node scripts/bump-version.js --patch --dry-run

GitHub repository settings (operator)

Configure once in GitHub (not in git):

1. Default branch → dev — new clones and PRs target active development.
2. Protect main — require PR, require status checks (Web Console CI, Secret Scan, Version Verify), disallow direct push.
3. Optional: protect dev — require CI on PRs without release checklist.

Update channel (stable / development)

Installations pull updates from a GitHub branch:

Channel	Branch	Use case
Stable	main	Production (default)
Development	dev	Early testing

Panel (Settings → Updates)

Select Stable (main) or Development (dev) and click Apply channel. The setting is stored in web-nodejs/.env as UPDATE_GITHUB_BRANCH. Systemd loads it via EnvironmentFile; Windows NSSM loads .env at console startup.

After switching channel, run Check for updates — the tracked commit SHA is kept, so the first check against a new branch may show a large diff.

Installer scripts

• Linux: betterdesk.sh → Update → Switch update channel
• Windows: betterdesk.ps1 → Update → Switch update channel
• Docker: betterdesk-docker.sh → Update → Switch update channel

Environment variable (all paths):

UPDATE_GITHUB_BRANCH=main   # stable
UPDATE_GITHUB_BRANCH=dev    # development

CI workflows

Workflow	Trigger	Action
version-bump-dev.yml	Push to dev	Patch bump + commit [version-bump]
version-bump-main.yml	PR merged to main	Minor bump, tag, GitHub Release
version-verify.yml	Push/PR touching version files	Fail if files disagree
release-server.yml	Tag v*	Go server binaries
docker-publish.yml	Tag, release, push to main/dev, or dispatch from version-bump-dev	GHCR images: on branch pushes, builds only version-bump subjects so image VERSION matches tip (#401); version-bump-dev dispatches tag=dev because GITHUB_TOKEN pushes do not re-trigger workflows. Tags/release/dispatch always build. latest on stable release/main; dev on development publishes; semver on v* / Release. AIO :dev is amd64-only; multi-arch on main/release/non-dev dispatch

First stable release note

If VERSION is 3.0.0 but no v3.0.0 tag exists yet, create it once manually after enabling this workflow, or merge the first PR to main to let CI publish v3.1.0.