Versioning Reference

This reference defines how version values are resolved in JSL and how to implement versioning consistently across project types.

JSL Version Resolution (Current Behavior)

From buildServiceProject.groovy, JSL resolves version in this order:

  1. If config.version is already set (for example from jenkins.yaml), keep it.

  2. Else if pom.xml exists, read project.version.

  3. Else run ./scripts/version.sh.

  4. If script fails, fallback to 1.0.0.

JSL also derives:

  • config.majorVersion from the first segment of the resolved version.

Deploy-Time Version Overrides

Manual deploy

Manual deploy stage uses:

  • DEPLOY_VERSION Jenkins parameter (highest precedence), else

  • deployVersion from jenkins.yaml

This value is passed to deploy commands as VERSION=…​.

Auto deploy

Auto deploy stages use:

  • config.version (resolved during build phase)

Java / Maven

  • Keep version in pom.xml as source of truth.

  • Avoid duplicating version in shell scripts unless needed for local tooling.

  • Use release branch process to manage final version transitions.

JavaScript / Node

  • Keep version in package.json.

  • Add scripts/version.sh that outputs exactly one clean version string.

  • Ensure local release tooling and CI call the same version source.

Example:

#!/usr/bin/env bash
set -euo pipefail
node -p "require('./package.json').version"

Go / Other

  • Define a project scripts/version.sh contract.

  • Prefer deriving from git tags or a single project manifest.

  • Keep the script deterministic (no network calls, no interactive input).

Migration Checklist

  1. Choose one source of truth (pom.xml, package.json, manifest, tag strategy).

  2. Implement/validate scripts/version.sh for non-Maven projects.

  3. Confirm produced value is semver-compatible with your deployment tooling.

  4. Verify image tags, deploy commands, and notifications all use the same version.

  5. Guard against fallback 1.0.0 in release flows.

Common Failure Modes

  • Script outputs extra text/newlines, causing malformed image tags.

  • Local version bump process differs from CI resolution path.

  • deployVersion is used as a permanent bypass instead of correcting source versioning.

  • Snapshot/release naming conventions differ between environments.

Extension Guidance

If you need new version behavior in JSL:

  1. Update version resolution logic in buildServiceProject.groovy (or extracted helper if introduced).

  2. Keep backward compatibility for Maven + scripts/version.sh flows.

  3. Add/update tests or validation jobs in a sample project.

  4. Update this reference and the main conversion guide.