mesos-reviews mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Anand Mazumdar" <mazumdar.an...@gmail.com>
Subject Re: Review Request 41661: Added documentation for API versioning.
Date Tue, 29 Dec 2015 20:47:33 GMT


> 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
> > <https://reviews.apache.org/r/41661/diff/4/?file=1176528#file1176528line31>
> >
> >     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
> > <https://reviews.apache.org/r/41661/diff/4/?file=1176528#file1176528line13>
> >
> >     "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
> 
>


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