> It is a compromise - it's an inconvenience to users, forcing them to fix scripts to upgrade. Which isn't good for user experience either; but it doesn't outright break people. It's a compromise I'm willing to live with.
It will literally outright break clients (*all* of them, not just *some*). We have been down this road before, so I'll just repeat what I said when this exact conversation came up months ago[1]: "So it basically boils down to: A) promote Go 1.x routes to 2.x and eventually break ALL users of the 1.x API when the time comes to remove 1.x B) deprecate and remove some 1.x Perl routes and POSSIBLY break SOME users" Either way we slice and dice it with versioning, removing an endpoint means that clients of that endpoint will break. By graduating only the "good stuff" from 1.x to 2.x, and removing endpoints from 1.x, we will unnecessarily break all 1.x clients when the time comes to remove the rest of 1.x. Instead, we can choose to break only clients of 1.x APIs that we already deemed dangerous, unnecessary, useless, etc. enough to deprecate. Why break 100% of our API clients when we can choose to break only a small number of clients that happen to use dangerous/unnecessary/useless APIs? Why would we break our API clients unnecessarily for no added value? There is no sense in blindly adhering to Semantic Versioning just for the sake of adhering to Semantic Versioning. Instead, use it as a guideline, and break the rules where it makes the most sense to do so. - Rawlin [1] https://lists.apache.org/thread.html/15c6bfcdce0ac00a3a8612a96c3d668a8a5a16c6ca9401de9473d31c@%3Cdev.trafficcontrol.apache.org%3E On Wed, Nov 13, 2019 at 9:43 AM Robert O Butts <[email protected]> wrote: > > > But if it's really valuable to remove these endpoints, maybe it's > appropriate to bump the major version and ask everybody to update their > clients? > > +1 > > This sounds like the best compromise to me. It addresses both sides - it > lets us remove endpoints, and it also prevents breaking users. > > It is a compromise - it's an inconvenience to users, forcing them to fix > scripts to upgrade. Which isn't good for user experience either; but it > doesn't outright break people. It's a compromise I'm willing to live with. > > This actually lets us do at least 3 things: > 1. Remove "deprecated" endpoints. > 2. Remove the unmaintained dangerously-large Cache Config endpoints. > 3. Lets us do Layered Profiles, changing Servers and DSes to have arrays of > Profiles instead of a single Profile, without hacky backward-compatibility > attempts. > > To clarify, `/api/2.0` would be essentially the current API, just with the > above breaking changes (possibly others) which require a SemVer major > version increase. And the big API rewrite/redesign we've been calling "2.0" > would become `/api/3.0` or some future version. > > It's not perfect, but it seems to address the most concerns on all sides. > Thoughts? Objections? > > > On Wed, Nov 13, 2019 at 8:45 AM Chris Lemmons <[email protected]> wrote: > > > For the endpoints, I agree in part and disagree in part. > > > > Agree for these two: > > - the endpoints are dangerous and pose a risk to the overall Traffic > > Control system > > - the task of rewriting the endpoints from Perl to Go represents an > > unreasonable amount of work for the project > > > > And I would add: > > - the endpoint does not serve its intended purpose and cannot reasonably > > be used > > - the endpoint has been made unsafe or unusable by new features added to TC > > > > Disagree for these two: > > - the endpoints have been obsoleted by other endpoints > > - the endpoints don't seem to serve a true purpose or don't seem to be > > valuable to the project anymore > > > > For the most part, obsoleted endpoints can be maintained with a shim > > into the new code. If they would require "an unreasonable amount of > > work", it might make sense to remove them, then. > > > > Things that don't seem valuable usually fall into another category > > like "cannot reasonably be used", but if the only reason for > > deprecation is that the feature is going away, we should really > > support it according to our promise. > > > > But if it's really valuable to remove these endpoints, maybe it's > > appropriate to bump the major version and ask everybody to update > > their clients? > > > > On Tue, Nov 12, 2019 at 5:27 PM Rawlin Peters <[email protected]> wrote: > > > > > > The real crux of the issue here is whether or not we agree as a > > > project that we can move forward with this plan that I believe to be a > > > good compromise that meets most concerns but "breaks the Semantic > > > Versioning promise": > > > 1) don't rewrite deprecated endpoints from Perl to Go > > > 2) in the Perl handler, add a deprecation notice to the "alerts" > > > section of the response > > > 3) once a deprecated API has been deprecated for one major release, > > > delete it from the API in the subsequent major release (e.g. if > > > deprecation notices are added and released in ATC 4.x, we can remove > > > the deprecated endpoint in ATC 5.x) > > > > > > Rob, from your latest proposal to remove the ATS config API endpoints > > > from 1.x, I thought we were past this issue already and could finally > > > agree to remove deprecated endpoints from 1.x (following steps 1-3 > > > above) without requiring an all-new 2.x API. Are we not actually past > > > that? You came up with valid reasons for applying these steps to the > > > ATS config API endpoints, and I think it's fair to say that we can > > > come up with valid reasons for applying these steps to other > > > deprecated API endpoints as well. > > > > > > It seems like the real problem is actually agreeing on which > > > _specific_ endpoints we should be able to follow steps 1-3 for. IMO I > > > think it should apply to any 1.x endpoints that we have valid reasons > > > for not carrying forward to Go, including but not limited to: > > > - the endpoints are dangerous and pose a risk to the overall Traffic > > > Control system > > > - the endpoints have been obsoleted by other endpoints > > > - the endpoints don't seem to serve a true purpose or don't seem to be > > > valuable to the project anymore > > > - the task of rewriting the endpoints from Perl to Go represents an > > > unreasonable amount of work for the project > > > > > > Obviously most of these reasons are subjective, so we'd have to come > > > to some level of consensus on deprecating particular endpoints first, > > > but we should be able to follow steps 1-3 for whatever endpoints we > > > decide. > > > > > > Making breaking changes shouldn't be taken lightly, but we need a path > > > forward that allows some calculated, breaking changes where necessary. > > > Otherwise, we are unnecessarily holding the project back. > > > > > > - Rawlin > > > > > > On Tue, Nov 12, 2019 at 11:44 AM Jeremy Mitchell <[email protected]> > > wrote: > > > > > > > > Yeah, technically a "rewrite" of 1.x means shifting the implementation > > from > > > > Perl to Go for ALL of 1.x. If you leave a subset of 1.x in Perl, then > > you > > > > have to call it a "partial rewrite". > > > > > > > > So, assuming we want to do a full rewrite (no more perl for the api > > > > whatsoever), I think that means every 1.x api endpoint (good or bad) > > needs > > > > to be rewritten to Go so we can remove the dependency on perl. > > > > > > > > However, I still like marking many as "deprecated" so we train users > > to use > > > > "better" endpoints that we envision will exist in 2.x and beyond. > > > > > > > > Jeremy > > > > > > > > On Tue, Nov 12, 2019 at 11:22 AM Hoppal, Michael < > > [email protected]> > > > > wrote: > > > > > > > > > We do not have a lot of deprecated routes as of now as we focused on > > > > > routes that are more used first. > > > > > > > > > > I know on a lot of the remaining rewrites there has been discussion > > on the > > > > > matching Github issues on potential deprecation (I cannot think of > > the > > > > > exact count but enough to warrant this email __) > > > > > > > > > > It is key to note that I am not arguing for removal of endpoints > > within > > > > > the current API version but if there is an endpoint we agree should > > be > > > > > deprecated going forward to put a message within the response and on > > the > > > > > docs. > > > > > > > > > > And thanks for the input sounds like you are +1 on rewriting all > > routes to > > > > > Golang as Brennan is. > > > > > > > > > > On 11/12/19, 9:06 AM, "Robert O Butts" <[email protected]> wrote: > > > > > > > > > > Whether we rewrite a route in Go is an implementation detail. To > > the > > > > > interface, to users, it doesn't matter whether a route is > > rewritten or > > > > > not. > > > > > > > > > > But our API follows Semantic Versioning, in order to not break > > users. > > > > > We > > > > > can't just remove endpoints that some of us don't use, and > > assume other > > > > > people don't, maybe people who never speak up on the mailing > > list. > > > > > We'll > > > > > never gain a big userbase if we keep breaking users. > > > > > > > > > > Per the _project_ SemVer, once we have API 2.0, we can deprecate > > API > > > > > 1.x, > > > > > and in the next major _project_ release, remove API 1.x. > > Irrespective > > > > > of > > > > > Perl or Go. > > > > > > > > > > My big concern is, API 2.0 is a big project. How long has the > > rewrite > > > > > to Go > > > > > taken? Do we really believe designing and implementing a > > completely > > > > > new API > > > > > will be any less time? > > > > > > > > > > I don't want killing Perl to have to wait on that. > > > > > > > > > > I know it feels like a waste to rewrite routes that you don't > > use, and > > > > > probably few people do. But that's the cost of a stable project. > > How > > > > > many > > > > > "deprecated" routes are there? If it comes down to taking the > > > > > development > > > > > time to rewrite them so we can kill Perl faster, or leaving Perl > > > > > around, I > > > > > vote we just do the work and kill Perl. > > > > > > > > > > >If we don't rewrite them, then Perl will last until API 2.0 has > > been > > > > > designed, released and then *another full major release cycle*. > > That's > > > > > way > > > > > too long to have two codebases for the same component, IMO, > > especially > > > > > since the rewrite is already 50% complete. > > > > > > > > > > +1 > > > > > > > > > > > > > > > On Tue, Nov 12, 2019 at 8:54 AM ocket 8888 <[email protected]> > > > > > wrote: > > > > > > > > > > > I vote that by and large we DO rewrite them, with exceptions > > for > > > > > routes > > > > > > that just plain don't work, even in Perl. Those are few, > > though. > > > > > > > > > > > > If we don't rewrite them, then Perl will last until API 2.0 > > has been > > > > > > designed, released and then *another full major release cycle*. > > > > > That's way > > > > > > too long to have two codebases for the same component, IMO, > > > > > especially > > > > > > since the rewrite is already 50% complete. > > > > > > > > > > > > On Tue, Nov 12, 2019 at 8:43 AM Hoppal, Michael < > > > > > > [email protected]> > > > > > > wrote: > > > > > > > > > > > > > As the Traffic Ops API is being rewritten from Perl to Golang > > > > > there has > > > > > > > been several routes that have been deprecated and probably > > more to > > > > > come. > > > > > > > > > > > > > > In the deprecation efforts I have seen two strategies: > > > > > > > > > > > > > > > > > > > > > * The route IS NOT rewritten from Perl to Golang and a > > > > > deprecation > > > > > > > notice is added to the alert response in the Perl handler > > > > > > > * The route IS rewritten from Perl to Golang and a > > deprecation > > > > > notice > > > > > > > is added to the alert response in the Golang handler > > > > > > > > > > > > > > I think we should have consistency in our approach and > > wanted to > > > > > get > > > > > > > people’s thoughts. > > > > > > > > > > > > > > I would vote that we do not rewrite a deprecated route from > > Perl to > > > > > > Golang. > > > > > > > > > > > > > > Thanks, > > > > > > > > > > > > > > Michael > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
