search

concourse / concourse-bosh-release

Concourse BOSH release
Apache License 2.0
28 stars 49 forks source link

Independent release cycle #21

Open vito opened 5 years ago

vito commented 5 years ago

We should give this release its own release cycle and its own release notes; cramming them into the concourse-ci.org release notes feels wrong, and depending on new versions of Concourse feels pretty limiting when it comes to BOSH-specific bugs like #18 and #19.

We'll need to come up with a versioning scheme that isn't coupled to Concourse versions, and be careful to note which Concourse version is embedded.

cirocosta commented 5 years ago

Hey,

As we moved Concourse into a direction where being part of a BOSH release is just a detail in the way that we distribute it, I personally feel that breaking from the version of Concourse is ideal.

Some rationale below.

Wdyt?

thx!

Not being tied to Concourse's release version

E.g.: v0.1.3 packaging Concourse v5.2.0.

Having the version of the release totally independent of Concourse itself, we can have the semantics of semver applied to the public interface that the package exposes, allowing one to know, e.g., if by upgrading, the new packaging will require changes or not.

For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number.

https://semver.org/

If we think the indirection required to determine Concourse's version is a problem, we can solve that by including metadata that makes that more obvious:

v0.1.3+5.2.0

Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version.

IMO being separate from Concourse's version is what best fits applying semver to concourse-bosh-release.

This type of versioning is followed by many releases:

Keeping the Concourse version as the BOSH release version

Proposal.: v5.2.0+1 where 1 is the version of the packaging of v5.2.0

For those concerned about which version of Concourse is contained within "the package" (the release), having the indication of the internal software's version in the version of the packaging helps.

Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

Pre-release indicator (-; e.g.: 1.0.0-123) doesn't seem to make sense as that indicates just the version of a pre-release. Build metadata tough (+; e.g. 1.0.0+1231233) could be used as a way of referring to the packaging of the Concourse as a BOSH RELEASE without changing the samantics of the software contained within the "package".

A possible problem here is that for build metadata, there's no precedence when comparing one version against another.

Build metadata SHOULD be ignored when determining version precedence.

Example releases are those where the source code is tightly coupled with the definition of the release (e.g., what Concourse what before):

vito commented 5 years ago

@cirocosta Thanks, that's a great summary. I prefer the first option as it sounds more semver-compliant and allows us to express breaking changes that we make to the release itself. Versions like v0.1.3+5.2.0 seem to have the best of both worlds.

One interesting case to consider is when Concourse does a major bump, that does not intrinsically imply a major bump of the BOSH release. This makes sense to me because what we're versioning here is the packaging and manifest structure, not Concourse itself. You could potentially go from v5.3.0 to v6.0.0 without changing your manifest at all.