Re: [asterisk-dev] AMI/ARI versioning

[Kevin Harwell]

In order to bring this topic to conclusion I think we'll move forward with
the following versioning model for AMI and ARI since it seems to have
garnered the most votes:

MAJOR.MINOR.PATCH

Where the following definitions apply:

MAJOR - changes when a new major version of Asterisk is released
MINOR - changes when an incompatible API modification is made
PATCH - changes when backwards compatible updates are made (new additions
or bug fixes)

This is basically option number 2 that was outlined in the "ARI versioning
in 13 and 14" thread [1].

I've created a page [2] on the Asterisk wiki for ARI and updated an
existing page for AMI [3] that essentially states the above for each.

Thanks to all for your input and suggestions!

[1] http://lists.digium.com/pipermail/asterisk-dev/2016-November/075964.html
[2] https://wiki.asterisk.org/wiki/display/AST/ARI+Versioning
[3]
https://wiki.asterisk.org/wiki/display/AST/Asterisk+Manager+Interface+%28AMI%29+Changes

Kevin Harwell
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [asterisk-dev] AMI/ARI versioning

[Matt Fredrickson]

On Fri, Mar 31, 2017 at 10:37 AM, Corey Farrell  wrote:
> On 03/31/2017 10:47 AM, Kevin Harwell wrote:
>
>
>
> On Thu, Mar 30, 2017 at 6:54 PM, Corey Farrell  wrote:
>>
>> On 03/30/2017 07:14 PM, Kevin Harwell wrote:
>> I think it's worth referencing a previous discussion on this [1].
>
>
> Yes, thank you! I looked for this and for some reason my searches turned up
> nothing.
>
>>
>> I agree with Mark's idea that having the ARI/AMI major version tied to the
>> Asterisk branch could lead to confusion, lead people to believe that ARI
>> 14.3.0 == Asterisk 14.3.0.
>
>
> Yeah I could see that causing confusion.
>
>>
>>
>> [1]
>> http://lists.digium.com/pipermail/asterisk-dev/2016-November/075964.html
>>
>
> Mark Michelson wrote:
>>
>> 2) Bump the major version of ARI for each major release of Asterisk. We
>> won't retroactively apply this to the upgrade from Asterisk 12 to
>> Asterisk 13. So Asterisk 13 will have ARI versions 1.X.Y, Asterisk 14
>> will have ARI versions 2.X.Y, and Asterisk 15 will end up with Asterisk
>> 3.X.Y
>
>
> I'm assuming the other numbers would just be reset here? For instance when
> Asterisk 15 is released it would it become 3.0.0?
>
> I think either way we do it the versioning ends up being somewhat localized
> to the associated branch and the major number can't change once set on a
> branch.
>
>
> Yes each new major version of Asterisk would start with AMI and ARI version
> X.0.0.  Once Asterisk 15 is released with ARI/3.0.0 we can't bump Asterisk
> 14 to also use ARI/3.x.x.  Although the versions are localized to the
> associated branch I think we should enforce that an older branch of Asterisk
> always has a lower major version for ARI/AMI.
>
> With version X.Y.Z, I think this should represent:
> X: architecture / Asterisk branch.  On bump of X all bets are off.  X is
> associated to a specific major version of Asterisk but not an equal number.
> Y: breaking change to existing features, but overall architecture in tact.
> Might break/remove a function or event, ignore a parameter, add a new
> required parameter, etc.
> Z: non-breaking change/addition: added optional parameter, new attribute in
> response, new function/event (including from any new module).
>
> So an app written for 3.0.0 should work unmodified against 3.0.1, but may
> require tweaks to work with 3.1.0.  An app written for 3.0.1 might work with
> 3.0.0, but not guaranteed if the app uses features added to 3.0.1.

I'm ok with this approach.  We've discussed the past once or twice.
I'd prefer if X were the major version of Asterisk, but I'm willing to
compromise that it at least be some sort of number mapping scheme.  I
kind of hate that we have to make a number map at all, but I
understand that concern and potential confusion.

-- 
Matthew Fredrickson
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA

-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [asterisk-dev] AMI/ARI versioning

[Corey Farrell]

On 03/31/2017 10:47 AM, Kevin Harwell wrote:



On Thu, Mar 30, 2017 at 6:54 PM, Corey Farrell > wrote:


On 03/30/2017 07:14 PM, Kevin Harwell wrote:
I think it's worth referencing a previous discussion on this [1].


Yes, thank you! I looked for this and for some reason my searches 
turned up nothing.


I agree with Mark's idea that having the ARI/AMI major version
tied to the Asterisk branch could lead to confusion, lead people
to believe that ARI 14.3.0 == Asterisk 14.3.0.


Yeah I could see that causing confusion.


[1]
http://lists.digium.com/pipermail/asterisk-dev/2016-November/075964.html



Mark Michelson wrote:

2) Bump the major version of ARI for each major release of
Asterisk. We
won't retroactively apply this to the upgrade from Asterisk 12 to
Asterisk 13. So Asterisk 13 will have ARI versions 1.X.Y, Asterisk 14
will have ARI versions 2.X.Y, and Asterisk 15 will end up with
Asterisk 3.X.Y


I'm assuming the other numbers would just be reset here? For instance 
when Asterisk 15 is released it would it become 3.0.0?


I think either way we do it the versioning ends up being somewhat 
localized to the associated branch and the major number can't change 
once set on a branch.


Yes each new major version of Asterisk would start with AMI and ARI 
version X.0.0.  Once Asterisk 15 is released with ARI/3.0.0 we can't 
bump Asterisk 14 to also use ARI/3.x.x.  Although the versions are 
localized to the associated branch I think we should enforce that an 
older branch of Asterisk always has a lower major version for ARI/AMI.


With version X.Y.Z, I think this should represent:
X: architecture / Asterisk branch.  On bump of X all bets are off. X is 
associated to a specific major version of Asterisk but not an equal number.
Y: breaking change to existing features, but overall architecture in 
tact.  Might break/remove a function or event, ignore a parameter, add a 
new required parameter, etc.
Z: non-breaking change/addition: added optional parameter, new attribute 
in response, new function/event (including from any new module).


So an app written for 3.0.0 should work unmodified against 3.0.1, but 
may require tweaks to work with 3.1.0.  An app written for 3.0.1 might 
work with 3.0.0, but not guaranteed if the app uses features added to 3.0.1.
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [asterisk-dev] AMI/ARI versioning

[Daniel Journo]

I agree with Mark's idea that having the ARI/AMI major version tied to the 
Asterisk branch could lead to confusion, lead people to believe that ARI 14.3.0 
== Asterisk 14.3.0.

Is it possible to use letters instead of numbers to avoid confusion?

ARI 14.A.1 ?

Or use numbers which aren’t Asterisk versions?

ARI 14.100.1 ?

So you can still keep the Asterisk version at the start?

-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [asterisk-dev] AMI/ARI versioning

[Kevin Harwell]

On Thu, Mar 30, 2017 at 6:54 PM, Corey Farrell  wrote:

> On 03/30/2017 07:14 PM, Kevin Harwell wrote:
> I think it's worth referencing a previous discussion on this [1].
>

Yes, thank you! I looked for this and for some reason my searches turned up
nothing.


> I agree with Mark's idea that having the ARI/AMI major version tied to the
> Asterisk branch could lead to confusion, lead people to believe that ARI
> 14.3.0 == Asterisk 14.3.0.
>

Yeah I could see that causing confusion.


>
> [1] http://lists.digium.com/pipermail/asterisk-dev/2016-
> November/075964.html
>
>
Mark Michelson wrote:

> 2) Bump the major version of ARI for each major release of Asterisk. We
> won't retroactively apply this to the upgrade from Asterisk 12 to
> Asterisk 13. So Asterisk 13 will have ARI versions 1.X.Y, Asterisk 14
> will have ARI versions 2.X.Y, and Asterisk 15 will end up with Asterisk
> 3.X.Y


I'm assuming the other numbers would just be reset here? For instance when
Asterisk 15 is released it would it become 3.0.0?

I think either way we do it the versioning ends up being somewhat localized
to the associated branch and the major number can't change once set on a
branch.
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [asterisk-dev] AMI/ARI versioning

[Corey Farrell]

On 03/30/2017 07:14 PM, Kevin Harwell wrote:



[asterisk-branch-number].[minor].[patch]


Actually, the proposal might be better represented as the following:

[asterisk-branch-number].[major].[minor/patch]

Or another way to state it:

[asterisk-branch-number].[api breaking].[api non breaking]


I think it's worth referencing a previous discussion on this [1].  I 
agree with Mark's idea that having the ARI/AMI major version tied to the 
Asterisk branch could lead to confusion, lead people to believe that ARI 
14.3.0 == Asterisk 14.3.0.


[1] http://lists.digium.com/pipermail/asterisk-dev/2016-November/075964.html
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [asterisk-dev] AMI/ARI versioning

[Kevin Harwell]

>
>
> [asterisk-branch-number].[minor].[patch]
>
>
Actually, the proposal might be better represented as the following:

[asterisk-branch-number].[major].[minor/patch]

Or another way to state it:

[asterisk-branch-number].[api breaking].[api non breaking]
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [asterisk-dev] AMI/ARI versioning

[Phil Mickelson]

I think that's a wonderful idea!  I use ARI only.

Thanks!
Phil Mickelson
CBA Software, Inc.

On Thu, Mar 30, 2017 at 6:43 PM, Kevin Harwell  wrote:

> Greetings,
>
> (I believe this topic has been brought up before, but I was unable to
> locate the thread)
>
> In theory, AMI/ARI versions follow the semantic versioning pattern [1].
> The major version number of each started at 1 (1.0.0) and is supposedly
> bumped when a new major version of the API is released.
>
> However, in practice the API's major version is usually bumped when a new
> major version of Asterisk is released and not changed otherwise. This is
> done in order to alleviate API maintenance burdens, and the weird situation
> one could get into where an older version of Asterisk specifies a higher
> AMI/ARI version number than a newer version of Asterisk. For instance,
> because what could be a breaking API change in Asterisk 13 (version bumped)
> may not be in Asterisk 14 (version not bumped). So in reality Asterisk
> AMI/ARI API's exhibit the following pattern:
>
> [asterisk-branch-number].[minor].[patch]
>
> With the exception that currently the major version number is not actually
> the Asterisk branch number. In order to bring that more into alignment it
> has been proposed to do just that. Make the major number the same as the
> associated Asterisk branch number. So AMI/ARI API version numbers would
> then start with 13.x.x for Asterisk 13 and 14.x.x for Asterisk 14.
>
> Thoughts and opinions?
>
> [1] http://semver.org/
> --
>
> Kevin Harwell
> Digium, Inc. | Software Developer
> 445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
> Check us out at: http://digium.com & http://asterisk.org
>
>
> --
> _
> -- Bandwidth and Colocation Provided by http://www.api-digital.com --
>
> asterisk-dev mailing list
> To UNSUBSCRIBE or update options visit:
>http://lists.digium.com/mailman/listinfo/asterisk-dev
>
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

[asterisk-dev] AMI/ARI versioning

[Kevin Harwell]

Greetings,

(I believe this topic has been brought up before, but I was unable to
locate the thread)

In theory, AMI/ARI versions follow the semantic versioning pattern [1]. The
major version number of each started at 1 (1.0.0) and is supposedly bumped
when a new major version of the API is released.

However, in practice the API's major version is usually bumped when a new
major version of Asterisk is released and not changed otherwise. This is
done in order to alleviate API maintenance burdens, and the weird situation
one could get into where an older version of Asterisk specifies a higher
AMI/ARI version number than a newer version of Asterisk. For instance,
because what could be a breaking API change in Asterisk 13 (version bumped)
may not be in Asterisk 14 (version not bumped). So in reality Asterisk
AMI/ARI API's exhibit the following pattern:

[asterisk-branch-number].[minor].[patch]

With the exception that currently the major version number is not actually
the Asterisk branch number. In order to bring that more into alignment it
has been proposed to do just that. Make the major number the same as the
associated Asterisk branch number. So AMI/ARI API version numbers would
then start with 13.x.x for Asterisk 13 and 14.x.x for Asterisk 14.

Thoughts and opinions?

[1] http://semver.org/
-- 

Kevin Harwell
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev