This is an automatically generated e-mail. To reply, visit:

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

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 

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)


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 

- 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

Reply via email to