Maybe I'm nit-picking, but I thought you mean only API versioning, which does not include release versioning, to which "Updates" section is related. I would propose to make the sentence more catchy: convert it to `NOTE` and state clear the whole doc (not just API versioning) applies to Mesos 1.0+ only.
On Mon, Jan 4, 2016 at 7:33 PM, Anand Mazumdar <an...@mesosphere.io> wrote: > Vinod alluded to a similar concern as a review comment and we added the > following to the beginning of the doc: > > “API versioning was introduced in Mesos 0.24.0 and this scheme only applies > to Mesos 1.0.0 and higher.” > > I was under the impression that the above statement should suffice? > > -anand > > >> On Jan 4, 2016, at 3:02 AM, Alex R <ruklet...@gmail.com> wrote: >> >> The "Upgrades" section says "The master and agent are typically compatible >> as long as they are running the same major version.". Is my understanding >> correct that this will apply to 1.0.0+ versions? Currently we advice people >> not to skip any Mesos releases, could you please clarify that in the doc? >> >> >> On 31 December 2015 at 02:12, <vinodk...@apache.org> wrote: >> >>> Repository: mesos >>> Updated Branches: >>> refs/heads/master b54d9ee06 -> 4568e584d >>> >>> >>> Added documentation for API versioning. >>> >>> Review: https://reviews.apache.org/r/41661/ >>> >>> >>> Project: http://git-wip-us.apache.org/repos/asf/mesos/repo >>> Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/4568e584 >>> Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/4568e584 >>> Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/4568e584 >>> >>> Branch: refs/heads/master >>> Commit: 4568e584d15e2da68f777aff2570d6b0ceaa14fa >>> Parents: b54d9ee >>> Author: Anand Mazumdar <mazumdar.an...@gmail.com> >>> Authored: Wed Dec 30 17:11:21 2015 -0800 >>> Committer: Vinod Kone <vinodk...@gmail.com> >>> Committed: Wed Dec 30 17:11:21 2015 -0800 >>> >>> ---------------------------------------------------------------------- >>> docs/home.md | 1 + >>> docs/versioning.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++ >>> 2 files changed, 101 insertions(+) >>> ---------------------------------------------------------------------- >>> >>> >>> http://git-wip-us.apache.org/repos/asf/mesos/blob/4568e584/docs/home.md >>> ---------------------------------------------------------------------- >>> diff --git a/docs/home.md b/docs/home.md >>> index d929838..6f0f4b9 100644 >>> --- a/docs/home.md >>> +++ b/docs/home.md >>> @@ -54,6 +54,7 @@ layout: documentation >>> * [Javadoc](/api/latest/java/) documents the Mesos Java API. >>> * [Doxygen](/api/latest/c++/namespacemesos.html) documents the Mesos C++ >>> API. >>> * [Developer Tools](/documentation/latest/tools/) for hacking on Mesos or >>> writing frameworks. >>> +* [Versioning](/documentation/latest/versioning/) describes how Mesos >>> does API and release versioning. >>> >>> ## Extending Mesos >>> >>> >>> >>> http://git-wip-us.apache.org/repos/asf/mesos/blob/4568e584/docs/versioning.md >>> ---------------------------------------------------------------------- >>> diff --git a/docs/versioning.md b/docs/versioning.md >>> new file mode 100644 >>> index 0000000..7af6581 >>> --- /dev/null >>> +++ b/docs/versioning.md >>> @@ -0,0 +1,100 @@ >>> +--- >>> +layout: documentation >>> +--- >>> + >>> +# Mesos Versioning >>> + >>> +The Mesos API and release versioning policy gives operators and >>> developers clear guidelines on: >>> + >>> +* Making modifications to the existing APIs without affecting backward >>> compatibility. >>> +* How long a Mesos API will be supported. >>> +* Upgrading the Mesos installation across release versions. >>> + >>> +API versioning was introduced in Mesos 0.24.0 and this scheme only >>> applies to Mesos 1.0.0 and higher. >>> + >>> +## Terminology >>> + >>> +* **Release Versioning**: This refers to the version of Mesos that is >>> being released. It is of the form **Mesos X.Y.Z** (X is the major version, >>> Y is the minor version, and Z is the patch version). >>> +* **API Versioning**: This refers to the version of the Mesos API. It is >>> of the form **vX** (X is the major version). >>> + >>> +## How does it work? >>> + >>> +The Mesos APIs (constituting Scheduler, Executor, Internal, >>> Operator/Admin APIs) will have a version in the URL. The versioned URL will >>> have a prefix of **`/api/vN`** where "N" is the version of the API. The >>> "/api" prefix is chosen to distinguish API resources from Web UI paths. >>> + >>> +Examples: >>> + >>> +* http://localhost:5050/api/v1/scheduler : Scheduler HTTP API hosted by >>> the master. >>> +* http://localhost:5051/api/v1/executor : Executor HTTP API hosted by >>> the agent. >>> + >>> +A given Mesos installation might host multiple versions of the same API >>> i.e., Scheduler API v1 and/or v2 etc. >>> + >>> +### API version vs Release version >>> + >>> +* To keep things simple, the stable version of the API will correspond to >>> the major release version of Mesos. >>> + * For example, v1 of the API will be supported by Mesos release >>> versions 1.0.0, 1.4.0, 1.20.0 etc. >>> +* vN version of the API might also be supported by release versions of >>> N-1 series but the vN API is not considered stable until the last release >>> version of N-1 series. >>> + * For example, v2 of the API might be introduced in Mesos 1.12.0 >>> release but it is only considered stable in Mesos 1.21.0 release if it is >>> the last release of “1” series. Note that all Mesos 1.x.y versions will >>> still support v1 of the API. >>> +* The API version is only bumped if we need to make a backwards >>> [incompatible](#api-compatibility) API change. We will strive to support a >>> given API version for at least a year. >>> +* The deprecation clock for vN-1 API will start as soon as we release >>> “N.0.0” version of Mesos. We will strive to give enough time (e.g., 6 >>> months) for frameworks/operators to upgrade to vN API before we stop >>> supporting vN-1 API. >>> +* Minor release version is bumped roughly on a monthly cycle to give a >>> cadence of new features to users. >>> + >>> +NOTE: Presently, for "0.X.Y" releases i.e. till we reach "1.0.0", we wait >>> for at least 6 monthly releases before deprecating functionality. So, >>> functionality that has been deprecated in 0.26.0 can be safely removed in >>> 0.32.0. >>> + >>> +### API Compatibility >>> + >>> +The API compatibility is determined by the corresponding protobuf >>> guarantees. >>> + >>> +As an example, the following are considered "backwards compatible" >>> changes for Scheduler API: >>> + >>> +* Adding new types of Calls i.e., new types of HTTP requests to >>> "/scheduler". >>> +* Adding new optional fields to existing requests to "/scheduler". >>> +* Adding new types of Events i.e., new types of chunks streamed on >>> "/scheduler". >>> +* Adding new header fields to chunked response streamed on "/scheduler". >>> +* Adding new fields (or changing the order of fields) to chunks’ body >>> streamed on "/scheduler". >>> +* Adding new API resources (e.g., "/foobar"). >>> + >>> +The following are considered backwards incompatible changes for Scheduler >>> API: >>> + >>> +* Adding new required fields to existing requests to "/scheduler". >>> +* Renaming/removing fields from existing requests to "/scheduler". >>> +* Renaming/removing fields from chunks streamed on "/scheduler". >>> +* Renaming/removing existing Calls. >>> + >>> +## Upgrades >>> + >>> +* The master and agent are typically compatible as long as they are >>> running the same major version. >>> + * For example, 1.3.0 master is compatible with 1.13.0 agent. >>> +* In rare cases, we might require the master and agent to go through a >>> specific minor version for upgrades. >>> + * For example, we might require that a 1.1.0 master (and/or agent) be >>> upgraded to 1.8.0 before it can be upgraded to 1.9.0 or later versions. >>> + >>> +The detailed information about upgrading to a particular Mesos version >>> would be posted [here](/documentation/latest/upgrades/). >>> + >>> +### Implementation Details >>> + >>> +Most APIs in Mesos accept protobuf messages with a corresponding JSON >>> field mapping. To support multiple versions of the API, we decoupled the >>> versioned protobufs backing the API from the “internal” protobufs used by >>> the Mesos code. >>> + >>> +For example, the protobufs for the v1 Scheduler API are located at: >>> + >>> +``` >>> +include/mesos/v1/scheduler/scheduler.proto >>> + >>> +package mesos.v1.scheduler; >>> +option java_package = "org.apache.mesos.v1.scheduler"; >>> +option java_outer_classname = "Protos"; >>> +… >>> +``` >>> + >>> +The corresponding internal protobufs for the Scheduler API are located at: >>> + >>> +``` >>> +include/mesos/scheduler/scheduler.proto >>> + >>> +package mesos.scheduler; >>> +option java_package = "org.apache.mesos.scheduler"; >>> +option java_outer_classname = "Protos"; >>> +… >>> +``` >>> + >>> +The users of the API send requests (and receive responses) based on the >>> versioned protobufs. We implemented [evolve]( >>> https://github.com/apache/mesos/blob/master/src/internal/evolve.hpp)/[devolve](https://github.com/apache/mesos/blob/master/src/internal/devolve.hpp) >>> converters that can convert protobufs from any supported version to the >>> internal protobuf and vice versa. >>> + >>> +Internally, message passing between various Mesos components would use >>> the internal unversioned protobufs. When sending response (if any) back to >>> the user of the API, the unversioned protobuf would be converted back to a >>> versioned protobuf. >>> >>> >
