Clarify release procedure for Swagger spec v 2.0

[vlcinsky]

(note, this issue was moved from forked repo reverb#129)
It is nice to see Swagger Spec v 2.0 published.

However, I have found it confusing, that the document https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md exists and history claims that is is released, while having a lot of notes like TODO or "need to add more..." places.

First a question: Is this really a release or there are plans to modify it?

Expectations

For documents of this type (some sort of specifications trying to become standard) it is essential to develop trust to stability of content under given reference.

It is anti-pattern to call something a release and change it later on without modifying name of the document (typically the version)

Usually, specifications like these are released in some upfront agreed/announced way.

Sample approach

Here is sample approach (there are many alternatives).

Document stages

• Version 2.0 Draft1 (implementing first set of predefined features)
• Version 2.0 Draft2 (enhancing Draft2 with new scope definition)
• .....
• Version 2.0 DraftN (trying to complete what is left)
• Version 2.0 Version for approval (no new features are expected)
• Version 2.0 release
• Version 2.0 revision (only correcting typos etc.)

Rules

• Draft can change any time, it is by definition work in progress document and is best not to be referenced.
• Release document must get unique identifier or url and must never change the content.
• Revisions might be released only, if released document contains errors and typos. It must never introduce new concepts.

Tips to make the process simpler

To make this process simpler, it is often practical to split the material to at least two parts:

• Standard itself - keep it as succinct and short as possible. Priority is: provide complete and correct specification of the topic described. Most of the parts shall be normative.
• Tutorial - Here you can move freely and explain the topic with examples. Priority: Support understanding of basic concepts. No need to cover all aspects of the standard.

See RELAX NG spec and tutorial as good example.

How to distinguish document stages

Use specific document names

• All documents are expected to live under master branch
• Stages are distinguished by document name
• Maintainer must take care, not to modify published Release (it is fine to modify Draft)

Example url would be:

• https://github.com/wordnik/swagger-spec/blob/master/versions/2.0-Draft1.md
• https://github.com/wordnik/swagger-spec/blob/master/versions/2.0-Draft2.md
• https://github.com/wordnik/swagger-spec/blob/master/versions/2.0-Draft3.md
• https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md
• https://github.com/wordnik/swagger-spec/blob/master/versions/2.0r1.md

Alternatively there we could use versioning schema as used e.g. for Python package - see PEP 0440

Use branches (and tags)

In git it is easy to use branching which are ideal mean for developing drafts.

There could be branches

• v2.0-draft1
• v2.0-draft2
• v2.0-draft3

Finally we would merge it into master.

Adding a tag "2.0" or "Swagger v2.0" would be handy, but we should not rely on this.

Proposed next actions

Assuming, the current v 2.0 is not yet ready for release and there was already attempt to publish it, I would propose:

• plan to release version 2.1 under predefined rules
• version 2.1 would attempt to provide the same concepts as in 2.0, but in clean way.
• agree on some procedure and rules for releasing (branches, document names, something else)
• describe it in this repo as Rules of procedures
• split the specification into core (succinct normative document) and Tutorial (which might be released independently and later on)
• work on releasing normative part
• give colleagues 2-3 weeks for comments on 2.1 proposal (aiming only in editorial cleanup of already present concepts, not improving them)
• release 2.1
• possibly work on tutorial (which does not have to follow strict procedure).

I am aware, that there is huge amount of effort in current content of 2.0 and my comments seem like bunch of formal difficulties. However, if you look to this from specification user standpoint, you might admit, that these formal rules add to usability of it.

[gregmac]

The swagger-spec README has this very confusing wording:

"The current version of the Swagger specification is 2.0 - and you can find it here."
"This repository contains the existing Swagger 1.2 specification as well as proposals for the 2.0 version."

The fact that the first version of swagger-ui to support spec 2.0 (swagger-ui 2.0.25) says it is "in development" leads me to believe this is not yet finalized. Yet swagger-spec says "current is 2.0" (as opposed to "2.0 is in development").

Please clarify this, and update READMEs as needed.

[ccleve]

+1. Is this thing released or not?

[fehguy]

The spec is released. The source of truth is the document, which may have further tuning, examples, etc:

https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md

The tooling has not been released and is "in development". That includes swagger-ui, swagger-js, swagger-core, swagger-codegen. They are separate from the spec.

[gregmac]

The final point is that the spec changed after it was "released".

Specifically, 4746200, a33091a and 34793ee were done AFTER the September 9 release date, but are not mentioned in the release history nor do they have a new version number. These are not what I'd call "tweaks", they actually change the specification. If someone implements a UI with the specification retrieved on September 9, it might not correctly render an API written by someone who used the specification from today.

The other commits that fix typos and formatting should really get done as part of the draft stage -- that is partially the point of having a draft prior to a final release.

The problem may be that your definition of "release" is different from mine: to me, "Released" implies "final". As in, "this is 2.0 and it won't change, ever".

I think what we are trying to say in this thread is:

• If you are going to "release" a specification, it should be complete (not full of "TODOs")
• If the specification is not final, call it a "draft"
• You can always release a new version (with a higher version number) when you want to make changes

@vlcinsky already highlighted how this can be done. I'd add that using semantic versioning would be appropriate and make determining compatibility easier on everyone.

Swagger is a very cool concept and is starting to get traction, but I'm saddened to see this irresponsible handling of versioning and changes potentially undermining the project.

[fehguy]

Understood. While successful to most, it has not been perfect, as you've pointed out.

[jharmn]

Closing as this is pretty darn old, and OAI has this better documented going forward: https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md

[gregmac]

You still have not actually addressed the issued raised. If a specification changes functionally (regardless of backwards-compatibility), its version number should change.

Specifically, from https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md:

The specification will change from the original 2.0 version. We should typically do so when any of the following criteria are met:

• Clarity. The current "way" something is done doesn't make sense, is complicated, or not clear
• Consistency. A portion of the specification is not consistent with the rest, or the industry standard terminology
• Necessary functionality. We are missing functionality because of a certain design of the specification
• Forward-looking designs. As usage of APIs evolves to new protocols, formats, patterns, we should always be considering what the next important functionality should be
• Impact. A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven.

Improvements that change examples, wording, descriptions, that is fine. Where I disagree is that new features, changes to field names, etc, deserve a new version number. It can be 2.0.1, but it should be distinct from 2.0.

Don't get me wrong: evolution of the spec is essential and absolutely a good thing. My disagreement is with "releasing" something you call "2.0", then changing it, and continuing to call it "2.0".

I see since I last commented there have again been a handful of additional spec changes that IMHO would deserve a new version. For an example of this, see: swagger-api/swagger-ui#1934. Swagger-ui that supposedly works with 2.0 is no longer fully compatible with 2.0 due to a modification that changed what 2.0 is six months after release. I'm sure if I went looking I'd find dozens of other examples across all the tooling that exists.

Anyway I'm not working on my own tooling or directly with the spec anymore (thankfully the ecosystem has matured to the point I don't have to) so I don't really have skin in the game so to speak, other than being a user of the tools and fan and advocate of the project itself.

Maybe it's not a big issue right now because the new features have been pretty small, but unchecked, eventually there will be a bunch of tools and APIs that simply don't fully work with each other, despite all saying they support Swagger/OpenAPI 2.0. It devalues the project and I think that's a shame.

Really, this is such a simple issue to fix (make a change, call the new version "2.0.1") that I just don't comprehend why this discussion even has to happen.

[fehguy]

@gregmac we're doing our best here with the time & resources we have. We will have a tighter process for the next spec version, and no, it won't be 2.0.