Skip to content

Change of versioning agreement #6195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
medikoo wants to merge 3 commits into from
Closed

Change of versioning agreement #6195

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
599e196
Update versioning agreement
medikoo May 30, 2019
4b07336
Improvements
medikoo May 30, 2019
9839cdc
Fix spelling
medikoo May 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 26 additions & 14 deletions VERSIONING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
# Versioning

For the framework we follow Semantic Versioning as defined on [http://semver.org/](http://semver.org).
For the framework we _do not follow_ Semantic Versioning per se (as defined on [http://semver.org/](http://semver.org)).

## Intepretation of SemVer for the Framework
However we ensure no breaking changes to be introduced with PATCH releases.

In `package.json` it is advised to reference a `serverless` dependency prefixed with a `~`, as e.g. `~1.44.1`. It allows PATCH updates but disallows MINOR updates which _may_ be breaking and MAJOR updates which are breaking.

## Intepretation of the version changes for the Framework

### PATCH

Expand All @@ -14,15 +18,19 @@ In version 1.2.0 we deployed a new version for every function. In 1.3.0 we stopp

### MINOR

If a release adds functionality in a backwards-compatible manner and contains backwards-compatible bug fixes. So whenever a new CLI option is added, a new property exposed in the serverless object passed to plugins this counts as new functionality.
Release containing new functionality in a backwards-compatible manner, backwards-compatible bug fixes. So whenever a new CLI option is added, a new property exposed in the serverless object is passed to plugins this counts as new functionality.

A MINOR release may also contain design improvements to existing features, which may not be backwards-compatible. In such case release notes will contain precise information on breaking changes and explain migration steps.

#### Example of a new Feature

In version 1.2.0 no profile option for the CLI existed and it should be introduced in the next release. Then the next version will be 1.3.0.

### MAJOR
#### Example of a Breaking Change

If we remove a helper function from the serverless object passed down to a plugin then this is a breaking change since some people might rely on it in custom made plugins.

Any non-backward compatible changes leads to a major version bump. This includes:
##### Other cases of breaking changes that may be released with MINOR

- Any change to the CloudFormation output that changes the behaviour of existing infrastructure
- Any change to the CloudFormation output that prevents you to deploy over an existing stack
Expand All @@ -31,8 +39,9 @@ Any non-backward compatible changes leads to a major version bump. This includes
- Any structural change in the CLI output
- Any object, property or function that is removed from the serverless object passed to plugins
- Remove an event from the list of lifecycle events of core commands
- Drop of support for no longer maintained major Node.js version (see [Node.js release schedule](https://github.com/nodejs/Release/blob/master/README.md))

#### What is considered a breaking change?
##### What is considered a breaking change?

- Everything which touches the public facing API
+ CLI commands
Expand All @@ -45,9 +54,12 @@ Any non-backward compatible changes leads to a major version bump. This includes
+ Formatted CLI outputs (e.g. via `--json`) **NOT:** standard outputs
+ ...

#### Example of a Breaking Change

If we remove a helper function from the serverless object passed down to a plugin then this is a breaking change since some people might rely on it in custom made plugins.
### MAJOR

Release containing a significant framwork upgrade that changes most of its functionalities or even drastically changes the framework design.

Breaking for all users of the framework.

### Node.js versions

Expand All @@ -57,16 +69,16 @@ The Serverless Framework supports the major cloud providers Node.js runtime vers

1. Is it okay to mark a feature as deprecated in version 1.4.0 and then remove it in 1.8.0

No, since this is a breaking change it should trigger a major version bump to 2.0.0
Yes, a breaking change to individual features may happen with a MINOR release

2. Can we change everything in a major version bump?
1. Can we change everything in a major version bump?

Yes, this is the purpose of major version bumps. Ideally every breaking change has a clear and well documented migration path. In best case the features were already introduced earlier and upgrading is not a dealbreaker.
Yes, a new major will most likely announce a completely new (or significantly changed) framework architecture

3. Can we do a major version bump without a breaking change?
1. Can we do a major version bump without a breaking change?

No, as we strictly follow Semantic Versioning. The suggested strategy is to add features with minor releases and only do major version bumps when we take out deperecated features. Sometimes this is not possible, but as suggested above then a well documented migration path should come with the release.
No, it won't happen

4. Why is CLI output a breaking change?
1. Why is CLI output a breaking change?

Right now we don't provide an option to output a well formated datastructure for a CLI command. Once we have such an option the default CLI output will not be part of the breaking changes list, but rather the datastructure. Also to note here if we add to that datastructure it will not be a breaking change. If we remove or change something from that datastructure it is a breaking change.

@pmuens pmuens Jun 20, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After reading this again I think it doesn't really make sense.

Above we state that changing CLI stdout is not a breaking change. However here we say that it would be a breaking change until we introduce a formatted datastructure.

Isn't this a contradiction? Or am I missing something? 🤔

@medikoo medikoo Jun 20, 2019

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was left intact, but I understand it as:

  • Why is change of CLI output a breaking change?
  • It's because we do not provide a programmatically consumable alternative. Once we will provide it, we will categorize changes to human readable CLI output as non-breaking

Still I see it as controversial, as anyway I think we improve wording and fix typos of CLI output now, and do not announce such changes as breaking. So technically we do not perfectly comply to this

@pmuens pmuens Jun 21, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, true. I just stumbled upon this while reading it. It's very vague, up for interpretation and controversial.

Let's keep it for now (as nobody complained so far) and update it later on.