I'm fully +1 on Semantic Versioning. We discussed it briefly on the list a
long time ago, but we haven't really been doing it.
That said, versioning requires a lot of code/work that simply doesn't exist
today. That's the reason we haven't been doing it properly.
The Go Traffic Ops has Semantic Versioning built-in to the Routing, but
Perl support is close to nil. Perl currently has an easy way to say
"include all the routes in this version number", But there's no way to say
"this route is 1.2 only, and this route is 1.3 only" -- we'd have to
duplicate TrafficOpsRoutes.pm, with only a few lines changed, and likewise
duplicate changed functions. It needs a framework. Or we could just wait
until Perl goes away.
That said, Go, especially the client, doesn't completely support Minor
Versions like it should, either. Consider adding a new field to Delivery
Services. Per Semantic Versioning, that field MUST not be returned by the
old version `GET`, and MUST not be set if passed by a `POST`. The Go server
supports that in the Routing, via different endpoints, but there's no
Struct framework or pattern. And the client completely doesn't support it.
In Go, we probably need a set of anonymously-nested structs, `type
DeliveryServices12 struct { Foo int }; type DeliveryServices13 struct
{DeliveryServices12; Bar string}`. But that simply doesn't exist today, and
will take development time to write.
Option 2: Absolute Versioning. Instead of Semantic Versioning, we could
have a single version, and break compatibility with each new version. So,
all new features (breaking or not) would go in a new version, and all
clients must check the version, and refuse to operate on a different
version. So you'd be required to have a client version matching the server
version; users are not allowed to talk to new servers with old clients.
Option 3: No Versioning. We get rid of the version number. Endpoints are at
`/api/foo`. Over the last few years, we have _repeatedly_ broken the API
for the same version. A 1.2 client from three years ago will fail
catastrophically if connected to a Traffic Ops serving `/api/1.2` today. In
practice, as we've been developing, we have no version, the version number
is meaningless and confusing. If we're going to continue breaking
compatibility without updating the version number, we should get rid of it.
Then at least the version itself won't be confusing and painful.
What's the consensus here? Does everyone agree with Semantic Versioning? Do
we want to commit to requiring it? Is there a consensus? Or should we take
a vote, whether to require Semantic Versioning, Absolute Versioning, or No
Version?
On Thu, Oct 12, 2017 at 7:39 AM, Dave Neuman <[email protected]> wrote:
> Traffic ops currently does not handle versioning very well. I think we do
> support 1.1 and 1.2 versions of the API, but I think there are only a few
> (maybe asns and deliveryservices) that are actually different.
> Versioning is something we look to improve as we move to the golang version
> of the API.
>
> On Thu, Oct 12, 2017 at 6:50 AM, Eric Friedrich (efriedri) <
> [email protected]> wrote:
>
> > Does Traffic Ops expose a semantic version number as part of its API?
> >
> > http://semver.org/
> > "Given a version number MAJOR.MINOR.PATCH, increment the:
> >
> > 1. MAJOR version when you make incompatible API changes,
> > 2. MINOR version when you add functionality in a backwards-compatible
> > manner, and
> > 3. PATCH version when you make backwards-compatible bug fixes.
> >
> > “
> >
> > We have some TO clients and would like to improve their backwards
> > compatibility. Without this version number, it is not easy to determine
> > which fields in the API are supported by any given version.
> >
> > Thanks,
> > Eric
> >
> >
>
