Screwdriver's Version Numbers

[stjohnjohnson]

note: this is partially inspired by the npm version mishap that happened this past week

Screwdriver has some strange version numbers (as of 2/23):

• API is at v0.5.228
• UI is at v1.0.234
• Store is at v2.2.7
• Launcher is at v4.0.74

What version is Screwdriver at? What version should I be using?

It's clear that our versioning is really all over the place when it comes to user-facing resources. For our internal node modules or binaries I think we do a good job. So what can we do to make a better experience for those trying to consume our product?

First-pass Proposal

• Ship one version number for all user-consumable resources (docker image) of Screwdriver (api, ui, store, launcher)
• Version number respects semver (in the sense that bug is patch, feature is minor, breaking is major)
• UI, store, and launcher should continue to have their own semver-based versions, but treated as internal versions like our existing node modules
• Have two active branches in screwdriver-cd/screwdriver: master and stable
• Stable always ships an even numbered version while master always ships an odd numbered version
• Backwards compatible features and bugs are merged into stable upon completion
• Backwards incompatible features cause a bump of both stable and master upon release
• screwdriver-cd/screwdriver pipeline publishes all docker images and a single github release representing state of the world
• Individual changes (patch, minor, etc) are tracked via GitHub releases
• Overall changes are tracked in a single issue per even-numbered major version

At the end of the day, our users should be able to see the latest stable version of Screwdriver, what version they are on, what changed between then and now, and what they need to do to upgrade. All of that should be available somewhere on screwdriver-cd/screwdriver.

Research notes

Other OSS projects do things like:

• Develop all new features on a separate branch that pushes to a fake release like "test"
• Ship pre-releases to a version like "v1.10.0-alpha.1"
• Publish release notes in a CHANGELOG file per major/minor version
• Publish major PR or issue to track changelog between versions
• Have all user-shippable components into one repository so that one version represents state of world
• Odd numbered major versions are under active development while even numbered versions are stable

[petey]

I agree with shipping out consistently versioned docker images for our projects, and divorcing those versions from the versions of the apps they contain.

I'm not a fan of even/odd versions, or having multiple active long-lived branches. I think that just leads to confusion. I'd much rather we adopted a train model where we ship master every [six] weeks (minor version) or more frequently (patch releases for bug fixes), and always provide backwards compatibility for deprecated features with deprecation warnings. After some period of time, we remove those deprecated features and warnings and bump major/minor.

As always, changelogs for the system-as-a-whole and each component therein are a necessity.

[FenrirUnbound]

Separating docker images from the modules is something I completely agree with.

One thing I would add to your research is the common use of docker-specific repositories projects use. Examples are:

• https://github.com/cachethq/Docker
• https://github.com/jenkinsci/docker

As for separate release lines, I've worked on different projects that have taken both approaches. The largest difference that I've seen between the two is the maintenance efforts are different, and developers respect them differently. For example, folks that aren't confident in cherry-picking releases definitely won't enjoy supporting multiple release lines.

[stjohnjohnson]

Thanks for the feedback. I'm circling back on this because I've run into some fun issues using stable in Kubernetes because it's a floating tag. Some nodes have one version and others have a different version. Therefore I need to go and specify the exact tag I want to use on each system.

So let's review some feedback:

• Don't use even/odd versions
• Don't use multiple branches
• Only affect Docker tags (not GitHub releases or NPM packages)
• Changelogs needed
• Agree that we need single version numbers

How can we proceed with this? Let's assume that right now the version of Screwdriver is 4.0.74 (the highest of the ones I listed above). What can we do to consistently build 4.0.74 docker images of the UI, API, Store, and Launcher? Should we move them all into the API repo? Make a separate repo like @FenrirUnbound gave as an example?

[jithine]

Proposal.

1. API already have /versions end point. Enhance it to add a new field version

   {
   ...
   version: 5.1.2
   ...
   }

2. Define POST /versions which will be invoked as part of release process, which bumps up major/minor/patch as required. We will have to figure out how separate running release pipelines for API/Store/UI interacts and updates this to a single value.

3. While we create docker tags for various componets, refer to { GET /versions }.version and use that value to tag UI, API & Store

4. UI will show this version in footer as version for Screwdriver application. Clicking on version should show all changes in that version. Could be just an API end point which just shows version changes on individual libraries which makes Screwdriver. Related to https://github.com/screwdriver-cd/screwdriver/issues/485