2

Using Semantic Versioning, if one of the function of my API undergoes the following change:

foo(a, b)
->
foo(a, b, c) //c optional

Does that require a new major version, or can it be passed under a minor version?

3 Answers 3

0

Semantic Versioning 2.0.0 says:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

If your extra param is optional, it requires a MINOR version change. Else, it requires a MAJOR version change.

2
  • Even if the extra third parameter is optional, depending on the language a call to the function with three parameters will change the behaviour of the API (exception/ignorance -> actually doing something). What about it?
    – Kyll
    Jul 28, 2015 at 14:06
  • 1
    To avoid a major release, you could setup a new function, say fooFunction(a,b,c) (containing all the code) and make foo(a,b) call fooFunction(a,b,null). But as far as I know, if your API supports optional params, the language the call comes from is irrelevant. It will work. The client wouldn't know how many parameters you need anyway. So it all breaks down to how your API reacts to a variable number of parameters Jul 28, 2015 at 14:15
0

According to http://semver.org/

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

So if you change the function it'a a major change.

but if you were overloading the function with another signature and not breaking compatibility .. it's a minor

0

Using the strictest interpretation of semver 2.0, I would expect that to be a breaking (i.e. major) change. You're changing the signature of a public method, that means making an incompatible API change.

Using a shallow understanding of optional parameters, I'd say that's a backwards-compatible (i.e. minor) change. The method can still be called in all the ways it was previously, so no code that calls the old method will fail to compile.

However, after doing some more digging into how C# seems to handle optional parameters and method groups, I've settled on the conclusion that it's a breaking (i.e. major) change. C# allows higher-order operations (e.g. passing "delegates"), and changing a method to add an optional parameter breaks code that passes that method as a delegate.

To demonstrate this, this compiles:

static void Main()
{
    var _ = TakesBar(Bar);
}
static int TakesBar(Func<int, int> bar) => bar(0);
static int Bar(int x) => x + 1;

However, after changing the signature of Bar to add an optional parameter at the end, it no longer compiles, because Bar now has the wrong signature to be passed to TakesBar:

static void Main()
{
    var _ = TakesBar(Bar);
}
static int TakesBar(Func<int, int> bar) => bar(0);
static int Bar(int x, int y = 0) => x + y + 1;

In contrast, this still works:

static void Main()
{
    var _ = TakesBar(Bar);
}
static int TakesBar(Func<int, int> bar) => bar(0);
static int Bar(int x) => x + 1;
static int Bar(int x, int y) => x + y + 1;

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.