> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/ci-cd/package-versioning.md). # Package Versioning (Limited Preview) {% hint style="warning" %} **This feature is in limited preview** — it is available to selected customers only, and behaviour and commands may change based on feedback. Reach out to the flxbl team if you would like early access. {% endhint %} Manually maintained `versionNumber` fields in `sfdx-project.json` generate merge conflicts between pull requests and depend on developers remembering to bump them correctly. With server-managed versioning, package versions are computed at build time, and versioning decisions are expressed on the pull request. ## How it works Packages you opt in carry the placeholder version `0.0.0.NEXT` in `sfdx-project.json`. From then on, nobody edits that file to release a new version. Instead, when a merge triggers a build, codev looks at what landed since the last published version and works out the right bump: * A PR titled `fix(sales): correct rounding on totals` → **patch** (`2.4.1` → `2.4.2`) * A PR titled `feat(sales): add payment plans` → **minor** (`2.4.1` → `2.5.0`) * A PR titled `feat(sales)!: rework pricing API` → **major** (`2.4.1` → `3.0.0`) * Anything else → **patch**. codev never over-bumps on its own. {% hint style="info" %} If your repository squash-merges pull requests, the PR title becomes the commit message — so conventional-commit style PR titles drive day-to-day versioning. {% endhint %} When several PRs land between builds, each package takes the highest bump among them. The computed versions appear on the [Builds](/flxbl/codev/ci-cd/overview.md) page with every build, alongside where each version came from. ## Deciding the version on the pull request When the default is not what you want, declare the bump on the PR with a `/version` comment. It takes precedence over commit-derived intents: ``` /version sales:major ``` You can target several packages, or apply one intent to everything the PR changed: ``` /version sales:major sales-ui:minor ``` ``` /version minor ``` The plain form (`/version minor`) applies only to the packages **this PR** touched — comments on one PR never affect packages that only other PRs changed. If a change to a shared package should also bump the packages that depend on it, ask for that explicitly: ``` /version core-crm:minor dependents:patch ``` Every package that directly depends on `core-crm` gets a patch and is included in the next build, even though its own source did not change. **When a PR changes several packages**, each one is versioned independently from its own last published version. A scoped title like `feat(sales): ...` gives `sales` the minor and the other touched packages a patch; an unscoped `feat: ...` or a `/version minor` comment applies the intent to everything the PR touched; per-package entries (`/version sales:major`) always win for their package. For the full set of options — including `version:` commit footers and how scoping works when one commit touches several packages — see [Expressing version intent](https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning/expressing-version-intent). ## Enabling it **New projects** — toggle **Server-Managed Versioning** when creating the project. codev's onboarding preflight then resolves the current version of every package, records it on the sfp server, and includes the updated `sfdx-project.json` (all packages set to `0.0.0.NEXT`) in the configuration pull request it raises. Once that PR is merged, versions are computed from the next build onwards. **Existing projects** — open **Workflow Settings** on the Builds page and enable **Server-Managed Versioning**. The setting alone changes nothing: every package keeps behaving exactly as before until you opt it in. Then adopt at your own pace: * **One package at a time** — set a package's `versionNumber` to `0.0.0.NEXT` in a normal pull request and merge it. codev resolves the package's current version from its existing release history, and the package is server-managed from the next build. * **Everything at once** — run [`sfp project version seed`](https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning/adopting-automated-versioning) from the CLI to onboard all packages in one operation. Packages you have not opted in keep their existing behaviour — explicit versions are used as-is. A project can run with a mix of managed and manual packages, including across branches. ## Branches, cascades and hotfixes Versions are tracked per branch, and merges between branches reconcile automatically: the receiving branch never produces a version lower than anything the other line already published, and a change that was already versioned on one branch is not bumped again when it arrives on another — a feature shipped as `2.5.0` on `main` lands on a release branch as `2.5.1`, not `2.6.0`. This works hand-in-hand with [Cascades](/flxbl/codev/branch-operations/cascades.md), which keep your release branches in sync using proper merge commits. See [Versioning across branches](https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning/versioning-across-branches) for the details, including what happens when only one of two parallel branches has adopted automated versioning. ## Overriding and opting out * **Pin a specific version for one release** — set the package's `versionNumber` to an explicit value (e.g. `3.0.0.NEXT`); it is honoured verbatim and the package is back under server management as soon as you return it to `0.0.0.NEXT`. * **Opt out entirely** — [`sfp project version restore`](https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning/adopting-automated-versioning#opting-out-sfp-project-version-restore) writes the latest published versions back into `sfdx-project.json` and turns the feature off. Restoring selected packages (`-p sales`) keeps the feature on for the rest. ## Related * [Builds: What happens when code is merged](/flxbl/codev/ci-cd/overview.md) * [Cascades: Keep release branches in sync automatically](/flxbl/codev/branch-operations/cascades.md) * [sfp: Automated Package Versioning](https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning) * [sfp: Expressing version intent](https://docs.flxbl.io/flxbl/sfp/building-artifacts/automated-package-versioning/expressing-version-intent) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flxbl.io/flxbl/codev/ci-cd/package-versioning.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.