Clarify release procedure for Swagger spec v 2.0

[vlcinsky]

(note: issues do not belong to this forked repo, but to the original one at wrodnik, so I moved it there to OAI#107)
*do not comment here, but at OAI#107 *

It is nice to see Swagger Spec v 2.0 published.

However, I have found it confusing, that the document https://github.com/reverb/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/reverb/swagger-spec/blob/master/versions/2.0-Draft1.md
• https://github.com/reverb/swagger-spec/blob/master/versions/2.0-Draft2.md
• https://github.com/reverb/swagger-spec/blob/master/versions/2.0-Draft3.md
• https://github.com/reverb/swagger-spec/blob/master/versions/2.0.md
• https://github.com/reverb/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.

[fehguy]

@vlcinsky you're in the wrong repo. We've moved this to master:

https://github.com/wordnik/swagger-spec

I will make it clear in this one.

[vlcinsky]

Thanks @fehguy . For a moment, as I was checking proper wordnik swagger-spec repo, I was really afraid my issue got lost or I even suspected myself not to finish the issue submission (multitasking has some risks).

I moved the issue there.

There is couple of things, which prevented me from finding proper issue tracker:

• wordnik and rewerb are so close together
• I landed here either by googling or by clicking some of notifications sent here.
• there are so many issues around in this repo that I expected it must be "live" one.

[webron]

Cleaning this repo, closing this issue as it has moved to the original one.
OAI#107