Release Versions - r41d/ClusterDuck-Protocol GitHub Wiki

Author: Timo Wielink

Why this Document?

We need to track the updates and features being added to the CDP, we will define a standard of version numbers of the CDP based on Semantic versioning 2.0. 

Structure of version numbers

If you are adding a piece of code to the CDP we want to track all the changes being made, so everyone using the CDP knows what has been changed and most importantly knows its compatibility. We will base our version numbers on a very common standard called Semantic Versioning. This means that the Version number is based on 3 or 4 (If you have build numbers) numbers, that tell you where you are in development.

  • First Number: Tracks major changes

  • Second Number: Tracks minor changes

  • Third Number: Tracks patches or mere bug fixes

So for example, if the CDP is on V2.0.1 that means we are the second major update that likely won't work with V 1.x.x and that we have made no minor changes but we did patch one thing. 

If you want to understand what a change in version number means read down below.

Major Version Number Updates

When we make significant changes to a software product's API, we will increment the major version number. This means that the changes are extreme, to the point that they render the software incompatible with older versions. (Look at our 2.0.0 release that is not compatible with 1.0.0) At this point, the product has evolved drastically. It is no longer operating on the same vein as former versions. 

Minor Version Number Updates

The minor version number is incremented when we add a new feature to the product that is still compatible with former versions in the same major category. For example, a 2.1.0 version will still be compatible with 2.2.0. If we added minor version updates. With minor version updates, you will definitely see changes to the software's functionality and features. But the change is less noticeable.

Patches 

Patches are the small fixes and bugs that are noticed during the development. It means a fix or change to a current functionality inside the CDP. Compared to adding to its functionality since then it would be a minor change. Patches are often found during development and likely to be updated straight away by adding a small amount of code. 

Track Version Numbers in GitHub

We need to track these version numbers in GitHub and make the necessary releases to track compatibility. Every time a pull request is made you will need to specify the kind of change (Major, minor, or patch) in the Pull Request comments. The reviewer (Person to merge) will need to check if the following files are updated with the correct version number.  

After the Pull request is merged we need to decide if a GitHub Release is necessary. 

GitHub releases 

Together with the CDP Leadership team we are responsible for tracking version numbers and changes. If we think it's necessary to do an official GitHub release, because of many changes, we need to include the following information.

GitHub Release Template

Title (Should be the version number + "- DESCRIPTION")

Date

Description 

Release Information

  1. New in this release

  2. New Features

  3. Changes to existing features

  4. Unsupported or discontinued versions

  5. Fixed Issues

  6. Known Issues

  7. Related Documentation

  8. Special Considerations during an upgrade

Pull Requests

We need to know which features are added before we list them in the Release information that is why we will make a Pull Request template where you need to add the following.

GitHub Pull request template (WIP)

Description

Type

Patch

Major 

Minor

Related Issue

What have you added changed in functionality