Re: Traffic Ops API Semantic Versioning

[Chris Lemmons]

> do bug fixes qualify as breaking changes?

Not necessarily. I gave an example of one that did and one that
didn't. It's not the "bugfixiness" of it that matters, but whether it
breaks compatibility.

> It just feels to me like the TO API is a first class citizen of TC

Aye. But it's a citizen with different needs than most of the other
citizens. The numbers communicate different things. In TC, the version
number serves to organize work into discrete deliverable components
and the major and minor version numbers communicate the scope of the
changes to be expected. In TOAPI, the version number (imo) should
serve as a signifier of compatibility. A client should be able to
present its version to a server and be assured that its messages will
either be understood or rejected entirely, not misunderstood or
partially applied. A client should be able to ask a server for it's
version and be sure that the server version is sufficient for the
features the client wishes to use.

The goals are similar, but not really the same. Trying to apply the
TOAPI version to TC generally feels a bit like the tail wagging the
dog. Fundamentally, a Semver TOAPI version is descriptive and our TC
Version is prescriptive. I don't know that the two goals are
sufficiently aligned to keep them in lockstep.

On Thu, Oct 19, 2017 at 8:17 PM, Jeremy Mitchell  wrote:
> chris,
>
> the signing_algorithm thing does sound like a breaking change and sounds
> like it could warrant the move from 1.2 to 2.x...
>
> do bug fixes qualify as breaking changes?...hmm...i really hate to think
> that simple bug fixes would require a major version upgrade but i see your
> point.
>
> It just feels to me like the TO API is a first class citizen of TC (or soon
> will be) and like other TC components, it's version should follow along.
>
> Just my 2 cents. I know others feel like this could simplify a lot of
> things across components but I'll let them speak for themselves.
>
> Jeremy
>
> On Thu, Oct 19, 2017 at 5:03 PM, Chris Lemmons  wrote:
>
>> I think we can reasonably define "backwards-compatible change" to mean
>> "a client of the prior version can communicate with the future version
>> and all it's legitimate messages and sequences thereof are understood
>> to mean the same as they did in the prior version". We can reasonably
>> expect clients to ignore fields they do not understand in a response.
>>
>> Some examples:
>>
>> We add a new endpoint. This is backward compatible, because an old
>> client won't know to communicate with it.
>>
>> We add a field to an existing endpoint. For a read-only endpoint, this
>> is backward compatible. If the field is required on a post/put,
>> however, it would not be. Likewise, if the server assumes a "zero
>> value" instead of "not modified" on a post/put, that would also be not
>> backward compatible. If the field can be omitted, and the field isn't
>> modified on the server when it isn't present, it is backward
>> compatible.
>>
>> A more concrete example:
>>
>> In the URI Signing PR, we change the underlying database value from
>> "signed, boolean" to "signing_algorithm, varchar". Previously, the
>> "signed" boolean meant "using url_sig". Now that we're trying to add
>> "uri_signing" as an option, boolean doesn't make sense. But to
>> mitigate the change, we're leaving the existing API field "signed" as
>> a boolean that means "using url_sig".
>>
>> This is still not quite backward compatible, though. A client that
>> knows nothing of the new "signingAlgorithm" field can read a DS that
>> has "signed == false" and update it to "signed == true", then try to
>> undo it's change by reverting to what it used to be "signed == false".
>> For the old server version, this was a correct "undo" step. For the
>> new server version, this step can potentially change a DS from
>> "signingAlgorithm == uri_signing" to "signingAlgorithm == none". Since
>> the meaning of this sequence of messages is different, the change is
>> not backward compatible.
>>
>> A "bugfix" example:
>>
>> Hypothetically, we discover that when a client sends a zero value for
>> a latitude or longitude, we treat it as a "do not modify" instead of
>> actually setting the value to zero. This is not desired behaviour,
>> since there do exist legal lat/longs at the zero values (even if some
>> of them are very cold). So we fix the behaviour. Previously, a client
>> that didn't wish to modify the values could simply sent them to zero
>> when sending a message. Now, if the client did the same thing they
>> would wipe out existing lat/long values unintentionally. So, this fix
>> is not backward compatible.
>>
>> Even if we don't think anyone is using the previous behaviour, we
>> can't assume that. People don't have to ask permission of the TC team
>> to use the software or inform us that they are doing so. They don't
>> have to tell us about the clients they might have privately written
>> againt the API either.
>>
>> 

Re: Apache Traffic Control Code of Conduct

[Timilsina, Ashish]

Thanks Chris for your feedback. That sounds like a good plan so if no one has 
any objection to this, I will go ahead and fix the Code of Conduct based on the 
feedback below. 

On 10/18/17, 11:16 AM, "Chris Lemmons"  wrote:

I'm +1 on creating a CODE_OF_CONDUCT.md (or whatever the standard name
for the file is) and putting in a link to Apache's CoC. I'm, as I
mentioned, -1 on creating one unique to us or adopting a non-Apache
CoC.

Creating CODE_OF_CONDUCT.md (or appropriate) and adding it to the
bottom of our CONTRIBUTING.md (or appropriate) file will increase
discoverability and prevent future people from thinking we don't have
one. :) Apache's CoC is really well written, I think, and it's been
vetted by Apache Legal, which is a major plus.

On Wed, Oct 18, 2017 at 9:13 AM, Timilsina, Ashish
 wrote:
> Hi all,
>
> As we are discussing various things at the TC Summit here in Atlanta, Jan 
mentioned that our project needs a Code of Conduct which is extremely important 
as our community grows.
> I used the following 
(https://www.contributor-covenant.org/version/1/4/code-of-conduct.html) for our 
project and created a PR however, based on the feedback I got from 
@rob05c and @alficles, 
it seems like our project is already covered by the Apache foundation 
(https://www.apache.org/foundation/policies/conduct.html). So, instead of 
creating a new one like I did, we can just add the apache link in the 
“contribution.md” file.
> I want to get everyone’s opinion on this before I create another PR to 
modify our contribution page.
> Let me know if you have any questions.
>
> Sincerely,
> Ashish Timilsina
> Product Development Specialist | Comcast Technology Solutions
> 1899 Wynkoop St, Suite 550 | Denver, CO 80202
> M | 303-913-3379
> ashish_timils...@comcast.com

Re: Anonymous IP Blocking Flowchart

[Durfey, Ryan]

I would say if it is work in progress it would go in the wiki.  Once formally 
released to open source it would go here: 
http://trafficcontrol.apache.org/docs/latest/index.html .

Ryan DurfeyM | 303-524-5099
CDN Support (24x7): 866-405-2993 or 
cdn_supp...@comcast.com


From: "Eric Friedrich (efriedri)" 
Reply-To: "dev@trafficcontrol.incubator.apache.org" 

Date: Friday, October 20, 2017 at 8:58 AM
To: "dev@trafficcontrol.incubator.apache.org" 

Subject: Re: Anonymous IP Blocking Flowchart

Where do we think our “design docs” (diagrams and text) belong?

One option is the Wiki, but that can get stale so I’d toss it out there that 
PRs should include the obvious user facing docs, but also a design doc section 
as well

-Eric


On Oct 20, 2017, at 10:23 AM, Jeff Elsloo 
> wrote:
Hey Eric,
Thanks for sending this out. Hopefully we can build more of these
diagrams in the future to include in the docs. I'll try to put
something similar together for the stuff I've been working on.
--
Thanks,
Jeff
On Thu, Oct 19, 2017 at 1:55 PM, Eric Friedrich (efriedri)
> wrote:
Just realized the first diagram I put up was outdated
The response to anonymous IP blocking is actually configurable between a slate 
(302 redirect to a new URL) and a 403
—Eric
On Oct 19, 2017, at 10:53 AM, Eric Friedrich (efriedri) 
> wrote:
Here is flowchart requested at the summit. I’ll put this diagram along with the 
rest of the slides up soon
Its a link to a PNG despite the horribly formatted URL
https://cisco.box.com/s/4rwd6kk069vdmzxpp2ak0vt2elds0ufc
—Eric

Re: Anonymous IP Blocking Flowchart

[Eric Friedrich (efriedri)]

Where do we think our “design docs” (diagrams and text) belong? 

 One option is the Wiki, but that can get stale so I’d toss it out there that 
PRs should include the obvious user facing docs, but also a design doc section 
as well

-Eric


> On Oct 20, 2017, at 10:23 AM, Jeff Elsloo  wrote:
> 
> Hey Eric,
> 
> Thanks for sending this out. Hopefully we can build more of these
> diagrams in the future to include in the docs. I'll try to put
> something similar together for the stuff I've been working on.
> --
> Thanks,
> Jeff
> 
> 
> On Thu, Oct 19, 2017 at 1:55 PM, Eric Friedrich (efriedri)
>  wrote:
>> Just realized the first diagram I put up was outdated
>> 
>> The response to anonymous IP blocking is actually configurable between a 
>> slate (302 redirect to a new URL) and a 403
>> 
>> —Eric
>> 
>>> On Oct 19, 2017, at 10:53 AM, Eric Friedrich (efriedri) 
>>>  wrote:
>>> 
>>> Here is flowchart requested at the summit. I’ll put this diagram along with 
>>> the rest of the slides up soon
>>> 
>>> Its a link to a PNG despite the horribly formatted URL
>>> https://cisco.box.com/s/4rwd6kk069vdmzxpp2ak0vt2elds0ufc
>>> 
>>> —Eric
>>> 
>>> 
>> 

Re: Anonymous IP Blocking Flowchart

[Jeff Elsloo]

Hey Eric,

Thanks for sending this out. Hopefully we can build more of these
diagrams in the future to include in the docs. I'll try to put
something similar together for the stuff I've been working on.
--
Thanks,
Jeff


On Thu, Oct 19, 2017 at 1:55 PM, Eric Friedrich (efriedri)
 wrote:
> Just realized the first diagram I put up was outdated
>
> The response to anonymous IP blocking is actually configurable between a 
> slate (302 redirect to a new URL) and a 403
>
> —Eric
>
>> On Oct 19, 2017, at 10:53 AM, Eric Friedrich (efriedri)  
>> wrote:
>>
>> Here is flowchart requested at the summit. I’ll put this diagram along with 
>> the rest of the slides up soon
>>
>> Its a link to a PNG despite the horribly formatted URL
>> https://cisco.box.com/s/4rwd6kk069vdmzxpp2ak0vt2elds0ufc
>>
>> —Eric
>>
>>
>