Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Neil Conway

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review112196
---


What do you think about using "APIs" instead of "API's"? I think it is clearer, 
style-wise.

Should we use backticks for endpoint suffixes like `/api/vN` etc?

Content-wise: if we're writing user-facing documentation, I would spend less 
time motivating the introduction of the feature ("Without a clear versioning 
policy, the world sucked! So we had to change Mesos in the following way: 
..."), and more time just talking about the status quo ("The Mesos API 
versioning policy gives operators and developers clear guidelines for how long 
a Mesos API will be supported. It does this by ...")

Also, it seems weird to have "Release Versioning" down at the end of a document 
that is labeled "API Versioning". The difference between the two isn't clear 
(until you read carefully). How about we call the document "Mesos Versioning 
Policy", then start by talking about API versus release versions, and go from 
there?


docs/versioning.md (line 13)


"the Scheduler HTTP API", I'd think?

"dealing with upgrades"



docs/versioning.md (line 18)


"of the form"



docs/versioning.md (line 29)


Maybe clarify that this means a given Mesos installation might expose two 
versions of an endpoint, say at `/v1` and `/v2`.



docs/versioning.md (line 31)


Doesn't seem all that relevant in a user-facing document. It certainly 
doesn't belong this early.



docs/versioning.md (line 39)


I'd move this toward the end of the document.



docs/versioning.md (line 80)


"/foobar"



docs/versioning.md (line 89)


This is actually what users care about (as well as the "Upgrades" section); 
I would make this more prominent, e.g., move it closer to the start of the 
document.


- Neil Conway


On Dec. 27, 2015, 9:08 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 27, 2015, 9:08 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Vinod Kone

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review112266
---

Ship it!



docs/versioning.md (line 13)


We should make it clear that this versioning scheme applies from Mesos 1.0 
onwards.



docs/versioning.md (line 29)


,i.e.,



docs/versioning.md (line 39)


This seems to be in conflict with #31 above? Can you just move #31 here and 
delete the current wording in #39?



docs/versioning.md (line 74)


Not sure this belongs in the user doc. It's only relevant for mesos devs.



docs/versioning.md (lines 104 - 110)


you can kill this.


- Vinod Kone


On Dec. 29, 2015, 9:08 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 29, 2015, 9:08 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Anand Mazumdar

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/
---

(Updated Dec. 30, 2015, 12:47 a.m.)


Review request for mesos, Neil Conway and Vinod Kone.


Changes
---

Review comments.


Bugs: MESOS-4192
https://issues.apache.org/jira/browse/MESOS-4192


Repository: mesos


Description
---

This change adds documentation on how Mesos does API versioning. It also has a 
section:
- On how API versioning and Release versioning are different.
- API compatibility/upgrade guarantees.
- Implementation Details.

Most of the information is taken from the design doc on Mesos HTTP API 
Versioning:
https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#


Diffs (updated)
-

  docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
  docs/versioning.md PRE-CREATION 

Diff: https://reviews.apache.org/r/41661/diff/


Testing
---

https://gist.github.com/hatred/1cc6db05d0ca51397886


Thanks,

Anand Mazumdar



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Mesos ReviewBot

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review112274
---


Patch looks great!

Reviews applied: [41661]

Passed command: export OS=ubuntu:14.04;export CONFIGURATION="--verbose";export 
COMPILER=gcc; ./support/docker_build.sh

- Mesos ReviewBot


On Dec. 30, 2015, 12:47 a.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 30, 2015, 12:47 a.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Anand Mazumdar


> On Dec. 29, 2015, 6:26 p.m., Neil Conway wrote:
> > What do you think about using "APIs" instead of "API's"? I think it is 
> > clearer, style-wise.
> > 
> > Should we use backticks for endpoint suffixes like `/api/vN` etc?
> > 
> > Content-wise: if we're writing user-facing documentation, I would spend 
> > less time motivating the introduction of the feature ("Without a clear 
> > versioning policy, the world sucked! So we had to change Mesos in the 
> > following way: ..."), and more time just talking about the status quo ("The 
> > Mesos API versioning policy gives operators and developers clear guidelines 
> > for how long a Mesos API will be supported. It does this by ...")
> > 
> > Also, it seems weird to have "Release Versioning" down at the end of a 
> > document that is labeled "API Versioning". The difference between the two 
> > isn't clear (until you read carefully). How about we call the document 
> > "Mesos Versioning Policy", then start by talking about API versus release 
> > versions, and go from there?

Thanks for the review Neil. It helped quite a bit in cleaning things up further.

- Changed all instances of API's to APIs.
- Removed the `Background` section completely as per our discussion. Instead, 
added a short paragraph about the status quo.
- Modified the document title to be "Mesos API and Release Versioning".

I moved the sections `API version vs Release verstion` and `Upgrades` up as per 
our discussion.


> On Dec. 29, 2015, 6:26 p.m., Neil Conway wrote:
> > docs/versioning.md, line 31
> > 
> >
> > Doesn't seem all that relevant in a user-facing document. It certainly 
> > doesn't belong this early.

Agreed. As per our discussion, I moved it to the end of the document.


> On Dec. 29, 2015, 6:26 p.m., Neil Conway wrote:
> > docs/versioning.md, line 13
> > 
> >
> > "the Scheduler HTTP API", I'd think?
> > 
> > "dealing with upgrades"

I removed this section completely as per our discussion.


- Anand


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review112196
---


On Dec. 29, 2015, 8:47 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 29, 2015, 8:47 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Anand Mazumdar

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/
---

(Updated Dec. 29, 2015, 8:47 p.m.)


Review request for mesos, Neil Conway and Vinod Kone.


Changes
---

Review Comments.


Bugs: MESOS-4192
https://issues.apache.org/jira/browse/MESOS-4192


Repository: mesos


Description
---

This change adds documentation on how Mesos does API versioning. It also has a 
section:
- On how API versioning and Release versioning are different.
- API compatibility/upgrade guarantees.
- Implementation Details.

Most of the information is taken from the design doc on Mesos HTTP API 
Versioning:
https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#


Diffs (updated)
-

  docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
  docs/versioning.md PRE-CREATION 

Diff: https://reviews.apache.org/r/41661/diff/


Testing
---

https://gist.github.com/hatred/1cc6db05d0ca51397886


Thanks,

Anand Mazumdar



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Neil Conway

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review112215
---

Ship it!


Ship It!


docs/home.md (line 58)


Per below, I'd opt for "Mesos Versioning" or "Mesos Versioning Policy"



docs/versioning.md (line 5)


Can we just call this "Mesos Versioning"? "Mesos API and Release 
Versioning" is pretty long.


- Neil Conway


On Dec. 29, 2015, 8:47 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 29, 2015, 8:47 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Mesos ReviewBot

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review112230
---


Patch looks great!

Reviews applied: [41661]

Passed command: export OS=ubuntu:14.04;export CONFIGURATION="--verbose";export 
COMPILER=gcc; ./support/docker_build.sh

- Mesos ReviewBot


On Dec. 29, 2015, 9:08 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 29, 2015, 9:08 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-29 Thread Anand Mazumdar

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/
---

(Updated Dec. 29, 2015, 9:08 p.m.)


Review request for mesos, Neil Conway and Vinod Kone.


Changes
---

Review comments


Bugs: MESOS-4192
https://issues.apache.org/jira/browse/MESOS-4192


Repository: mesos


Description
---

This change adds documentation on how Mesos does API versioning. It also has a 
section:
- On how API versioning and Release versioning are different.
- API compatibility/upgrade guarantees.
- Implementation Details.

Most of the information is taken from the design doc on Mesos HTTP API 
Versioning:
https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#


Diffs (updated)
-

  docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
  docs/versioning.md PRE-CREATION 

Diff: https://reviews.apache.org/r/41661/diff/


Testing
---

https://gist.github.com/hatred/1cc6db05d0ca51397886


Thanks,

Anand Mazumdar



Re: Review Request 41661: Added documentation for API versioning.

2015-12-28 Thread Jojy Varghese


> On Dec. 27, 2015, 3:25 a.m., Jojy Varghese wrote:
> > docs/versioning.md, line 62
> > 
> >
> > This section could use some formatting. 
> > 
> > Also, would be useful to take the reader through a complete example 
> > covering a message's external and internal path.
> 
> Anand Mazumdar wrote:
> Can you elaborate a bit more on what did you mean by:
> 
> ```This section could use some formatting.```

With the formatting fixed for the protobuff section, this looks good now. So we 
dont need formatting here. Dropping this one.

Could we walk the uninitiated reader through an example of how the protobuff 
versioning is handled internally and externally for 1 message?


- Jojy


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111919
---


On Dec. 27, 2015, 9:08 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 27, 2015, 9:08 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-27 Thread Anand Mazumdar

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/
---

(Updated Dec. 27, 2015, 9:08 p.m.)


Review request for mesos, Neil Conway and Vinod Kone.


Changes
---

Review comments


Bugs: MESOS-4192
https://issues.apache.org/jira/browse/MESOS-4192


Repository: mesos


Description
---

This change adds documentation on how Mesos does API versioning. It also has a 
section:
- On how API versioning and Release versioning are different.
- API compatibility/upgrade guarantees.
- Implementation Details.

Most of the information is taken from the design doc on Mesos HTTP API 
Versioning:
https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#


Diffs (updated)
-

  docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
  docs/versioning.md PRE-CREATION 

Diff: https://reviews.apache.org/r/41661/diff/


Testing
---

https://gist.github.com/hatred/1cc6db05d0ca51397886


Thanks,

Anand Mazumdar



Re: Review Request 41661: Added documentation for API versioning.

2015-12-27 Thread Anand Mazumdar


> On Dec. 27, 2015, 3:25 a.m., Jojy Varghese wrote:
> > docs/versioning.md, line 7
> > 
> >
> > ephasize 0.24.0 (in quotes). Same in other places.

I tried to be consistent to other docs and they did not have quotes.

e.g:
http://mesos.apache.org/documentation/latest/ssl/
http://mesos.apache.org/documentation/latest/framework-rate-limiting/
http://mesos.apache.org/documentation/latest/scheduler-http-api/


> On Dec. 27, 2015, 3:25 a.m., Jojy Varghese wrote:
> > docs/versioning.md, line 62
> > 
> >
> > This section could use some formatting. 
> > 
> > Also, would be useful to take the reader through a complete example 
> > covering a message's external and internal path.

Can you elaborate a bit more on what did you mean by:

```This section could use some formatting.```


- Anand


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111919
---


On Dec. 23, 2015, 2:09 a.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 23, 2015, 2:09 a.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-27 Thread Mesos ReviewBot

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111943
---


Patch looks great!

Reviews applied: [41661]

Passed command: export OS=ubuntu:14.04;export CONFIGURATION="--verbose";export 
COMPILER=gcc; ./support/docker_build.sh

- Mesos ReviewBot


On Dec. 27, 2015, 9:08 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 27, 2015, 9:08 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-26 Thread Jojy Varghese

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111919
---



docs/versioning.md (line 7)


ephasize 0.24.0 (in quotes). Same in other places.



docs/versioning.md (line 24)


Blank line after "Examples:"



docs/versioning.md (line 62)


This section could use some formatting. 

Also, would be useful to take the reader through a complete example 
covering a message's external and internal path.



docs/versioning.md (line 70)


Blank line here.



docs/versioning.md (line 78)


Blank line here. You might have to test the rendering of this document 
using website docker.


- Jojy Varghese


On Dec. 23, 2015, 2:09 a.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 23, 2015, 2:09 a.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Anand Mazumdar

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/
---

(Updated Dec. 22, 2015, 10:57 p.m.)


Review request for mesos, Neil Conway and Vinod Kone.


Changes
---

Review comments


Bugs: MESOS-4192
https://issues.apache.org/jira/browse/MESOS-4192


Repository: mesos


Description
---

This change adds documentation on how Mesos does API versioning. It also has a 
section:
- On how API versioning and Release versioning are different.
- API compatibility/upgrade guarantees.
- Implementation Details.

Most of the information is taken from the design doc on Mesos HTTP API 
Versioning:
https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#


Diffs (updated)
-

  docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
  docs/versioning.md PRE-CREATION 

Diff: https://reviews.apache.org/r/41661/diff/


Testing
---

https://gist.github.com/hatred/1cc6db05d0ca51397886


Thanks,

Anand Mazumdar



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Anand Mazumdar


> On Dec. 22, 2015, 11:55 p.m., Guangya Liu wrote:
> > docs/versioning.md, line 36
> > 
> >
> > Not clear for what does " It would be really hard to debug an error 
> > that happens with Scheduler v2 API, Executor v4 API interacting with Mesos 
> > cluster running Internal v6 API and Operator v7 API." mean? I think that 
> > even with API versioning, this problem is still difficult to debug, how can 
> > the API version help this issue?
> 
> Anand Mazumdar wrote:
> We have a single API version across all components in Mesos. So you won't 
> ever run into the version explosion problem i.e. you have different 
> components running on different versions.
> 
> If any of the components have a backward compatible change it would 
> result in a version upgrade for all the components. Does this help clear 
> things ?
> 
> Guangya Liu wrote:
> Yes, I know what you mean, but the sentense here to me is more like to 
> be: With API versioning, I can make the Scheduler v2 API, Executor v4 API 
> interacting with Mesos cluster running Internal v6 API and Operator v7 API be 
> easy to debug. what do you say?  ;-)
> 
> What about refine the sentense as this: 
> * **Avoiding version explosion**: It would be really hard to debug an 
> error that happens with Scheduler v2 API, Executor v4 API interacting with 
> Mesos cluster running Internal v6 API and Operator v7 API. By putting all the 
> APIs under one version, we avoid the version explosion problem.

Fixed.


- Anand


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111689
---


On Dec. 22, 2015, 10:57 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 22, 2015, 10:57 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Anand Mazumdar

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/
---

(Updated Dec. 23, 2015, 2:09 a.m.)


Review request for mesos, Neil Conway and Vinod Kone.


Changes
---

Review comments


Bugs: MESOS-4192
https://issues.apache.org/jira/browse/MESOS-4192


Repository: mesos


Description
---

This change adds documentation on how Mesos does API versioning. It also has a 
section:
- On how API versioning and Release versioning are different.
- API compatibility/upgrade guarantees.
- Implementation Details.

Most of the information is taken from the design doc on Mesos HTTP API 
Versioning:
https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#


Diffs (updated)
-

  docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
  docs/versioning.md PRE-CREATION 

Diff: https://reviews.apache.org/r/41661/diff/


Testing
---

https://gist.github.com/hatred/1cc6db05d0ca51397886


Thanks,

Anand Mazumdar



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Mesos ReviewBot

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111715
---


Patch looks great!

Reviews applied: [41661]

Passed command: export OS=ubuntu:14.04;export CONFIGURATION="--verbose";export 
COMPILER=gcc; ./support/docker_build.sh

- Mesos ReviewBot


On Dec. 23, 2015, 2:09 a.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 23, 2015, 2:09 a.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Anand Mazumdar


> On Dec. 22, 2015, 11:55 p.m., Guangya Liu wrote:
> > docs/versioning.md, line 22
> > 
> >
> > Not yours, but can you please add the following to "Terminology" 
> > section?
> > 
> > Scheduler API
> > Executor API
> > Internal API
> > Operator API
> > 
> > I did not get any explanation for those APIs except from a slides 
> > shared by @vinod in Seattle conference 
> > http://www.slideshare.net/mesosphere/mesos-http-api

I don't think the versioning document should cater to such trivial details. The 
Mesos Scheduler API is already linked from the Mesos homepage. The Executor API 
should be up there soon along with others ?

Also, this is what the description for them would look like:

Scheduler API: API for schedulers to interact with Mesos.
Executor API: API for executors to interact with Mesos.
Operator API: API for operators to interact with Mesos.
Internal API: API for internal communication between Mesos Master and Agent.

^^ Isn't this self-explantory ?


> On Dec. 22, 2015, 11:55 p.m., Guangya Liu wrote:
> > docs/versioning.md, line 36
> > 
> >
> > Not clear for what does " It would be really hard to debug an error 
> > that happens with Scheduler v2 API, Executor v4 API interacting with Mesos 
> > cluster running Internal v6 API and Operator v7 API." mean? I think that 
> > even with API versioning, this problem is still difficult to debug, how can 
> > the API version help this issue?

We have a single API version across all components in Mesos. So you won't ever 
run into the version explosion problem i.e. you have different components 
running on different versions.

If any of the components have a backward compatible change it would result in a 
version upgrade for all the components. Does this help clear things ?


- Anand


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111689
---


On Dec. 22, 2015, 10:57 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated Dec. 22, 2015, 10:57 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Guangya Liu


> On 十二月 22, 2015, 11:55 p.m., Guangya Liu wrote:
> > docs/versioning.md, line 22
> > 
> >
> > Not yours, but can you please add the following to "Terminology" 
> > section?
> > 
> > Scheduler API
> > Executor API
> > Internal API
> > Operator API
> > 
> > I did not get any explanation for those APIs except from a slides 
> > shared by @vinod in Seattle conference 
> > http://www.slideshare.net/mesosphere/mesos-http-api
> 
> Anand Mazumdar wrote:
> I don't think the versioning document should cater to such trivial 
> details. The Mesos Scheduler API is already linked from the Mesos homepage. 
> The Executor API should be up there soon along with others ?
> 
> Also, this is what the description for them would look like:
> 
> Scheduler API: API for schedulers to interact with Mesos.
> Executor API: API for executors to interact with Mesos.
> Operator API: API for operators to interact with Mesos.
> Internal API: API for internal communication between Mesos Master and 
> Agent.
> 
> ^^ Isn't this self-explantory ?

Fair enough, thanks.


> On 十二月 22, 2015, 11:55 p.m., Guangya Liu wrote:
> > docs/versioning.md, line 36
> > 
> >
> > Not clear for what does " It would be really hard to debug an error 
> > that happens with Scheduler v2 API, Executor v4 API interacting with Mesos 
> > cluster running Internal v6 API and Operator v7 API." mean? I think that 
> > even with API versioning, this problem is still difficult to debug, how can 
> > the API version help this issue?
> 
> Anand Mazumdar wrote:
> We have a single API version across all components in Mesos. So you won't 
> ever run into the version explosion problem i.e. you have different 
> components running on different versions.
> 
> If any of the components have a backward compatible change it would 
> result in a version upgrade for all the components. Does this help clear 
> things ?

Yes, I know what you mean, but the sentense here to me is more like to be: With 
API versioning, I can make the Scheduler v2 API, Executor v4 API interacting 
with Mesos cluster running Internal v6 API and Operator v7 API be easy to 
debug. what do you say?  ;-)

What about refine the sentense as this: 
* **Avoiding version explosion**: It would be really hard to debug an error 
that happens with Scheduler v2 API, Executor v4 API interacting with Mesos 
cluster running Internal v6 API and Operator v7 API. By putting all the APIs 
under one version, we avoid the version explosion problem.


- Guangya


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111689
---


On 十二月 22, 2015, 10:57 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated 十二月 22, 2015, 10:57 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Guangya Liu

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111679
---



docs/versioning.md (line 11)


it is better use /roles instead of not /roles.json cause it will be 
deprecated.

https://github.com/apache/mesos/blob/master/src/master/master.cpp#L792-L799



docs/versioning.md (line 64)


s/an/a



docs/versioning.md (line 79)


s/scheduler" ./scheduler".



docs/versioning.md (lines 91 - 94)


Shall we unify the time to month? e.g. 24 weeks -> 6months
4 weeks-> 1 month



docs/versioning.md (line 94)


s/atleast/at least


- Guangya Liu


On 十二月 22, 2015, 9:43 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated 十二月 22, 2015, 9:43 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Guangya Liu

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111689
---



docs/versioning.md (line 20)


1) work or works?
2) s/work ?/work?



docs/versioning.md (line 22)


Not yours, but can you please add the following to "Terminology" section?

Scheduler API
Executor API
Internal API
Operator API

I did not get any explanation for those APIs except from a slides shared by 
@vinod in Seattle conference http://www.slideshare.net/mesosphere/mesos-http-api



docs/versioning.md (line 36)


Not clear for what does " It would be really hard to debug an error that 
happens with Scheduler v2 API, Executor v4 API interacting with Mesos cluster 
running Internal v6 API and Operator v7 API." mean? I think that even with API 
versioning, this problem is still difficult to debug, how can the API version 
help this issue?


- Guangya Liu


On 十二月 22, 2015, 10:57 p.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated 十二月 22, 2015, 10:57 p.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>



Re: Review Request 41661: Added documentation for API versioning.

2015-12-22 Thread Guangya Liu

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/41661/#review111719
---



docs/versioning.md (line 30)


s/URL ?/URL?

Sorry, I should post this in previous patch.


- Guangya Liu


On 十二月 23, 2015, 2:09 a.m., Anand Mazumdar wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/41661/
> ---
> 
> (Updated 十二月 23, 2015, 2:09 a.m.)
> 
> 
> Review request for mesos, Neil Conway and Vinod Kone.
> 
> 
> Bugs: MESOS-4192
> https://issues.apache.org/jira/browse/MESOS-4192
> 
> 
> Repository: mesos
> 
> 
> Description
> ---
> 
> This change adds documentation on how Mesos does API versioning. It also has 
> a section:
> - On how API versioning and Release versioning are different.
> - API compatibility/upgrade guarantees.
> - Implementation Details.
> 
> Most of the information is taken from the design doc on Mesos HTTP API 
> Versioning:
> https://docs.google.com/document/d/1-iQjo6778H_fU_1Zi_Yk6szg8qj-wqYgVgnx7u3h6OU/edit#
> 
> 
> Diffs
> -
> 
>   docs/home.md 51c19bb9d0d74698fcdda6197d32ed8f4a57d7c9 
>   docs/versioning.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/41661/diff/
> 
> 
> Testing
> ---
> 
> https://gist.github.com/hatred/1cc6db05d0ca51397886
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>