mesos-reviews mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Neil Conway" <neil.con...@gmail.com>
Subject Re: Review Request 41661: Added documentation for API versioning.
Date Tue, 29 Dec 2015 18:26:51 GMT

-----------------------------------------------------------
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)
<https://reviews.apache.org/r/41661/#comment172524>

    "the Scheduler HTTP API", I'd think?
    
    "dealing with upgrades"



docs/versioning.md (line 18)
<https://reviews.apache.org/r/41661/#comment172523>

    "of the form"



docs/versioning.md (line 29)
<https://reviews.apache.org/r/41661/#comment172526>

    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)
<https://reviews.apache.org/r/41661/#comment172527>

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



docs/versioning.md (line 39)
<https://reviews.apache.org/r/41661/#comment172528>

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



docs/versioning.md (line 80)
<https://reviews.apache.org/r/41661/#comment172525>

    "/foobar"



docs/versioning.md (line 89)
<https://reviews.apache.org/r/41661/#comment172529>

    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
> 
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message