# Which Versioning Schema Should We Use?

## 1) SemVer (MAJOR.MINOR.BUGFIX)

Site: https://semver.org/

Examples

- `10.3.72`
- `6.31.2`
- `14.2.4`
- Every API and npm module uses this schema

**Pros**

- SemVer is best when you want everyone (all engineers, x-teamers, and leadership) to know when it is safe to upgrade to the latest version and what to expect from a release
- Intended for technical end users
- Most familiar version schema for engineers
- It ain't broken, so maybe we don't need to fix it?

**Cons**

- We don't know when a version was released to production; we just know there's a version out there
- X-teamers don't need to know the technical engineering aspects of what the version means to do their job

## 2) CalVer (YY.MM)

Site: https://calver.org

Examples

- `Ubuntu 21.04` (YY.MM) - Linux-based operating system
- `Twisted 21.2.0` (YY.MM.PATCH) - Python networking and asynchronous execution framework
- `Unity 2020.1.0` (YYYY.MINOR.PATCH) - Cross-platform game engine

**Pros**

- CalVer is intended for large applications and platforms with non-engineering users, who don't need to know the engineering parts of the application/platform
- Our project is time sensitive; it makes sense to tie our versioning to the date
- It's easier for engineers to communicate with non-engineers (like leadership and x-team) when this version was released

**Cons**

- Unfamiliar schema
- May be difficult to automate versioning (but I think we can figure it out)

## 3) CalVer + Commit Hash (YY.MM.DD-COMMIT)

Site: none (custom idea)

Examples

- `21.01.05-1eda24` (YY.MM.DD-COMMIT) - this is a custom idea from a former Goat team member

**Pros**

- CalVer is intended for big applications and platforms with non-technical users
- Our project is time sensitive; it makes sense to tie our versioning to the date
- It's easier for engineers to communicate with non-engineers (like leadership and x-team) when this version was released
- This versioning schema tells us which commit hash to verify in GitHub

**Cons**

- Unfamiliar schema
- May be difficult to automate versioning (but I think we can figure it out)
- X-teamers don't need to know the commit hash to do their job

# Arguments for CalVer

There are three pain points that CalVer will solve.

## When Do We Upgrade Major, Minor, and Patch Versions with Semantic Versioning?
**Problem**: I noticed on frontend teams (past/current) that this is done arbitrarily. We don't have a standard on when to upgrade major, minor, and patch versions. We're currently just updating the minor version with every feature PR. Rarely do we ever touch or discuss the major and patch versions.
**Solution**: with calendar versioning, **we don't need to create a complimentary standard on upgrading major, minor, and patch versions**. The timestamp is a more straightforward way of saying, "Hey here is what the code can do at this date!" than semantic versioning.

## Ease of Checking Versions in Production
**Problem**: if we deploy to production with semantic versioning, we would check the version in production -> check in GitHub/Kubedashian when it was tagged and released. We have to check a resource to see when it was deployed.
**Solution**: with calendar versioning, we check the version in production and immediately understand that the timestamp is when we tagged/released. **No need for an extra check in GitHub/Kubedashian. This removes an unnecessary step.**

## Frequent Deployments to Production
**Problem**: let's say we did have several deployments this month, we just know that production had semantic versions of `1.10.0`, `1.11.0`, `1.12.0`, `1.13.0`, and `1.14.0`. However, we have to check in GitHub/ Kubedashian what specific days we deployed those versions.
**Solution**: if it's easier to read and understand how often we're deploying the code, **the calendar version will keep us honest about what we can do to expedite our deployments from bimonthly to weekly to daily.**