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

Reply via email to