OpenBao versioning logic

[Scorpil]

Hey everyone, what are your thoughts on OpenBao's versioning logic. Here's my proposal:

• SemVer based versioning
• Major version 0 maintaining compatibility with Vault v. 1.14.x, not introducing any breaking changes there, back-porting any fixes
• Non-stable releases use postfix, e.g. 0.1.0-dev, 0.1.0-alpha.0, 0.1.0-beta.1 etc.
• From major version 1 onwards compatibility is best effort, but not guaranteed

Thoughts?

[cipherboy]

I think defining "maintaining compatibility" is the key here. We're liable to want to drop some plugins we don't have resources to maintain (both auth, storage, and secret). So perhaps sticking to "API compatibility" might be sufficient?

[cipherboy]

Starting on this thread is a parallel discussion on defining migration: https://github.com/orgs/openbao/discussions/55

[cipherboy]

While I do like the idea of starting with version 0, the one issue is there's a lot of documentation talking about version 1.x and some talking about version 0.x... If we start with 2.x or some other versioning scheme (than x.y.z), it becomes clearer we were talking about upstream (even when Vault is mentioned or not)... Thoughts?

[cipherboy]

Hmmm... Are we really planning on supporting multiple releases here? Or could we maybe use an incrementing build number (YYYYMMDD-NUM) instead?

[JanMa]

I don't think we discussed how many releases we want to support yet. But regardless of that, I think dropping semantic versioning in favor of build timestamps is not a valid option. We don't really gain anything by it and instead make it very confusing for our users to understand what to expect from a new release.

[cipherboy]

In general, the changelog will tell you what to find in the release, and is typical for consumers of upstream, as the static major version isn't enlightening as some people's bug fixes have been others' breaking changes... And so I'd argue upstream hasn't followed SemVer proper, but just used a similar format.

A rolling, linear version number clearly indicates that multiple series wouldn't be supported upstream. :-) The issue we have is that upstream, users are used to a set of three stable releases (n-2). Unless we want to devote the time to triaging and backporting bugs to stable release branches, without a commercial product or company backing it, it makes less sense, IMO, to do so. (Whether that's date or build number or something else, I do not care as much about.)

Using semantic versioning now, gives the impression that we could be open to doing parallel release branches (1.y-1.z &c), and so users will be prone to asking for it, when we lack the resources to do so.

(Edit to add: If and when we do get to the point of needing to do multiple release trees, we could switch to something semver equivalent then.)

[cipherboy]

Hmm, I think a single version number will break things with the built-in version checks. We might also need to choose a higher version number than the last one shipped by upstream: as you can see in #119, we check for a specific version. There's a few more places in the code where this happens, so forking should be at least at the current version, IMO, if we're looking to avoid things breaking.

So, I think this means we either need a v2.x or a v1.y where y >= 14.

[joewxboy]

In that case, beginning with v2.x will make it less likely that people will have an expectation that version numbers align with upstream, even though it also implies a breaking change.

[tvsaru]

The original proposal to stick to v1.14.x seems to be to use MPL-licensed source as basis for OpenBao. I checkedout the latest point release - 1.14.8 - and it seems to have few files - mostly in test and web ui - that have BUSL license.

> git checkout v1.14.8

> find . -type f |egrep -v '.git/' | tr '\n' '\0' | xargs -0  egrep 'BUSL-'
./ui/app/styles/utils/swagger.scss: * SPDX-License-Identifier: BUSL-1.1
./ui/app/templates/vault/cluster/policies/error.hbs:  SPDX-License-Identifier: BUSL-1.1
./ui/app/helpers/decode-uri.js: * SPDX-License-Identifier: BUSL-1.1
./ui/tests/acceptance/enterprise-replication-unsupported-test.js: * SPDX-License-Identifier: BUSL-1.1
./ui/lib/open-api-explorer/addon/components/swagger-ui.js: * SPDX-License-Identifier: BUSL-1.1
./ui/lib/open-api-explorer/addon/templates/components/swagger-ui.hbs:  SPDX-License-Identifier: BUSL-1.1
./ui/lib/open-api-explorer/addon/routes/index.js: * SPDX-License-Identifier: BUSL-1.1
./ui/lib/pki/addon/components/page/pki-issuer-list.ts: * SPDX-License-Identifier: BUSL-1.1
./ui/lib/pki/addon/components/page/pki-key-list.ts: * SPDX-License-Identifier: BUSL-1.1
./command/operator_raft_snapshot_inspect_test.go:// SPDX-License-Identifier: BUSL-1.1
./command/operator_raft_snapshot_inspect.go:// SPDX-License-Identifier: BUSL-1.1
./helper/testhelpers/consul/cluster_storage.go:// SPDX-License-Identifier: BUSL-1.1
./builtin/logical/transit/path_export_test.go:// SPDX-License-Identifier: BUSL-1.1
./vault/external_tests/consul_fencing_binary/consul_fencing_test.go:// SPDX-License-Identifier: BUSL-1.1

[tvsaru]

v1.14.2 seems to be the last release that doesn't have any BUSL-licensed files.

--
Another interesting point I noticed is that, in few point releases enos/modules files where changed to BUSL and then reverted to MPL in hashicorp/vault#24162 (v1.14.7).

[naphelps]

Features and bugfixes were added to Vault's main branch under the BUSL license and then backported to older release streams. Hashicorp did not always change back the license when backporting, whether in error or not.

The BUSL licensed source will have to be removed and/or originally substituted before OpenBao and have a first release.

[cipherboy]

Due to concerns noted above, we've opted to go with semver and a 2.0.0 initial GA version number. Thank you all for your input!