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