Merge pull request #1405 from OAI/issue-1384

Resolve TSC name changes per #1384

Author: darrelmiller

DEVELOPMENT.md

@@ -1,6 +1,6 @@
 ## Development Guidelines
 
-This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Contributor Board will initially follow these processes when merging changes from external contributors or from the TCB itself. This guideline document will be adjusted as practicality dictates.
+This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Steering Committee (TSC) will initially follow these processes when merging changes from external contributors or from the TSC itself. This guideline document will be adjusted as practicality dictates.
 
 ## OAI Specification Driving factors
 
@@ -21,14 +21,19 @@ The specification _will change_ from the original 2.0 version.  We should typica
 
  - Use GitHub for all spec designs, use cases, and so on.
  - As with 2.0, the **human readable** document is the source of truth.  If using a JSON Schema again to document the spec, it is secondary to the human documentation.  The documentation should live in a *.md file, in parallel to the 2.0 document (versions/3.0.0.md for example).
- - The `master` branch shall remain the current, released OpenAPI Specification (i.e., 2.0).  We will work in an OpenAPI.next branch, which shall be described and linked to on the **default** README.md on master.
+ - At any given time, there would be _at most_ 4 work branches. The branches would exist if work has started on them. Assuming a current version of 3.0.0:
+   - `master` - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted.
+   - `v3.0.1` - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications.
+   - `v3.1.0` - The next MINOR version.
+   - `v4.0.0` - The next MAJOR version.
+ - The `master` branch shall remain the current, released OpenAPI Specification.  We will describe and link the work branch(es) on the **default** README.md on master.
  - Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal.
- - New features should be done in feature branches which, upon approval, are merged into the OpenAPI.next branch.
+ - New features should be done in feature branches/forks which, upon approval, are merged into the proper work branch.
  - Use labels for the workflow of specification changes.  Examples of labels are `proposed`, `needs migration review`, `needs tooling review`, `needs documentation`, `rejected`, and `needs approval`.  These labels must be assigned by project committers.
  - An issue will be opened for each feature change.  Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change.
  - A PR will be used to describe the _proposed_ solution, and linked to the original issue.
  - Not all committers will contribute to every single proposed change.  There may be many open proposals at once, and multiple efforts may happen in parallel.
- - When the OpenApi.next spec is complete and approved for release, the branch will be merged to master.
+ - When the a work branch is ready and approved, the branch will be merged to master.
 
 ## Approving Changes
 
@@ -38,7 +43,7 @@ For each change in the specification we should _always_ consider the following:
  - Tooling.  Strive to support code generation, software interfaces, and spec generation techniques.  Some features may be impossible to support in different frameworks/languages.  These should be documented and considered during the change approval process.
  - Visualization.  Can the specification change be graphically visualized somehow in a UI or other interface?
 
-Spec changes should be approved by a majority of the committers.  Approval can be given by commenting on the issue itself, for example, "Approved by @fehguy".  After voting criteria is met, any committer can merge the PR. (**TODO**: we will want to formalize what voting criteria actually is).
+Spec changes should be approved by a majority of the committers.  Approval can be given by commenting on the issue itself, for example, "Approved by @webron".  After voting criteria is met, any committer can merge the PR. (**TODO**: we will want to formalize what voting criteria actually is).
 
 No change should be approved until there is documentation for it, supplied in an accompanying PR.
 

GOVERNANCE.md

@@ -0,0 +1,31 @@
+# Governance
+
+The OpenAPI Specification is a project of the Open API Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance).
+
+# Processes and procedures of the Technical Steering Committee (TSC)
+
+The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines.
+
+## 1. The establishment of roles and the responsibilities for each role
+
+Roles:
+
+* [Liaison](https://www.merriam-webster.com/dictionary/liaison) — Elected by TSC members in a plurality vote (oral count). Liaison represents the TSC to the OAI's Business Governing Board (BGB) at board meetings (though this itself does not confer voting rights) and is the public facing mouthpiece of the TSC.
+
+* [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible for approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. 
+
+* [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members.
+
+## 2. Adding members to the TSC
+
+At an open TSC meeting, the impending call-for-nominations period is communicated and subsequently tweeted, no more than once per quarter. Nominations for members happen at closed TSC meetings via a motion by a voting TSC member. A nominee must not receive negative votes from 25% or more of the TSC voting membership via a confidential vote held electronically within a week of the nomination. Approved nominees are expected to comport themselves during the provisional period of four weeks as full members of the TSC, though nominees do not have voting rights until their membership is confirmed. TSC subsequently votes on those nominees in the subsequent TSC meeting. At most there are four voting periods per year, with a minimum of 1 per year.
+
+## 3. Removal of membership from the TSC
+
+In dire situations, it may be necessary to remove a TSC member, such as behavior that violates the code of conduct (whether non-participation merits removal is a decision left to the TSC voting members). 75% vote (confidential, electronic) of the other TSC. members is required to remove a member. Otherwise, TSC members are removed when they renounce their position by informing the Liaison of their effective resignation date.
+
+## 4. Criteria for decisions
+
+The group will strive to achieve all decisions via unopposed consensus. When not possible, unresolved conflicts will be raised to the OAI's Technical Oversight Board (TOB).
+
+The TSC will maintain a publicly available document specifying the process in the contributor guidelines for how proposed changes are merged into the specification. The TSC will document and publicize the schedule of merge parties and release parties for the benefit of the developer community.

IMPLEMENTATIONS.md

@@ -1,10 +1,6 @@
 ### Implementations
 
-Below is a list of known tooling that implements the 3.0.0 specification. Because
-the 3.0.0 specification has not yet been released, refer to the details of projects listed below for any notes about stability and roadmap.  The process 
-to create the best possible 3.0.0 specification includes feedback from end-users
-and tooling creators. We strongly encourage draft tooling be
-made available for early users of the OAS.
+Below is a list of known tooling that implements the 3.0.0 specification. While support for the 3.0.0 specification matures,  refer to the details of projects listed below for any notes about stability and roadmap.  The process to improve the 3.x specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts.
 
 These tools are not necessarily endorsed by the OAI.
 
@@ -18,15 +14,18 @@ These tools are not necessarily endorsed by the OAI.
 | openapi3-ts | [GitHub/metadevpro/openapi3-ts](https://github.com/metadevpro/openapi3-ts) | TypeScript | TS Model & utils for OpenAPI 3.0.x contracts |
 | swagger2openapi | [GitHub/mermade/swagger2openapi](https://github.com/mermade/swagger2openapi) | Node.js | An OpenAPI / Swagger 2.0 to OpenAPI 3.0.x converter and validator |
 | Tavis.OpenApi | [GitHub/tavis-sofware/Tavis.OpenApi](https://github.com/tavis-software/Tavis.OpenApi/) | dotnet | C# based parser with definition validation and migration support from V2 |
+| odata-openapi | [GitHub/oasis-tcs/odata-openapi](https://github.com/oasis-tcs/odata-openapi) | XSLT | OData 4.0 to OpenAPI 3.0.0 converter |
 
 
 #### Editors
 
 | Title          | Project Link | Language |Description                          |
 |----------------|--------------|----------|---------------------|
+| Apicurio Studio | [GitHub/Apicurio/apicurio-studio](https://github.com/Apicurio/apicurio-studio) | Java/Typescript | Web-Based **visual designer** for OpenAPI 2.0 and 3.0.0. |
 | KaiZen OpenAPI Editor | [GitHub/RepreZen/KaiZen-OpenAPI-Editor](https://github.com/RepreZen/KaiZen-OpenAPI-Editor) | Java | Eclipse Editor for OpenAPI 2.0 and 3.0 |
 | RepreZen API Studio | [RepreZen.com/OpenAPI](https://www.reprezen.com/OpenAPI) | Java | Commercial desktop IDE for API design, documentation & development |
 | OpenApi-gui | [GitHub/Mermade/openapi-gui](https://github.com/Mermade/openapi-gui) | Node.js | GUI / visual editor for creating and editing OpenApi / Swagger definitions |
+| SwaggerHub | [swaggerhub.com](https://swaggerhub.com) | | API Design and Documentation Platform, Built For Teams
 | swagger-editor | [GitHub/swagger-api](https://github.com/swagger-api/swagger-editor) | JavaScript | Web-Based editor for creating, editing, validating and testing OpenAPI\Swagger definitions |
 
 #### User Interfaces
@@ -35,6 +34,7 @@ These tools are not necessarily endorsed by the OAI.
 |----------------|--------------|----------|---------------------|
 | openapi-viewer | [GitHub/koumoul/openapi-viewer](https://github.com/koumoul-dev/openapi-viewer) | Vue.js | Browse and test a REST API described with the OpenAPI 3.0 Specification. |
 | swagger-ui | [GitHub/swagger-api](https://github.com/swagger-api/swagger-UI) | JavaScript | Web-Based interface for visualizing and testing OpenAPI\Swagger definitions |
+| lincoln | [GitHub/temando/open-api-renderer](https://github.com/temando/open-api-renderer)| React.js| A React renderer for Open API v3 |
 
 
 #### Server Implementations
@@ -46,3 +46,5 @@ These tools are not necessarily endorsed by the OAI.
 |----------------|--------------|----------|---------------------|
 | baucis-openapi3 | [Github/metadevpro/baucis-openapi3](https://github.com/metadevpro/baucis-openapi3) | Node.js | [Baucis.js](https://github.com/wprl/baucis) plugin for generating OpenAPI 3.0 compliant API contracts. |
 | Google Gnostic | [GitHub/googleapis/gnostic](https://github.com/googleapis/gnostic) | Go | Compile OpenAPI descriptions into equivalent Protocol Buffer representations. |
+| serverless-openapi-documentation | [GitHub/temando/serverless-openapi-documentation](https://github.com/temando/serverless-openapi-documentation) | Typescript | Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration |
+| zero-rails_openapi | [GitHub/zhandao/zero-rails_openapi](https://github.com/zhandao/zero-rails_openapi) | Ruby | Provide concise DSL for generating the OpenAPI Specification 3 documentation file for Rails application |

README.md

@@ -20,6 +20,10 @@ This GitHub project is the starting point for OpenAPI. Here you will find the in
 
 The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.0.md).
 
+### Future Versions
+
+[3.0.1](https://github.com/OAI/OpenAPI-Specification/tree/v3.0.1) - The next PATCH version. Patch-level fixes (typos, clarifications, etc.) should be submitted against this branch.
+
 ### Previous Versions
 
 This repository also contains the [OpenAPI Specification 2.0](versions/2.0.md), which is identical to the Swagger 2.0 specification before it was renamed to "OpenAPI Specification", as well as the Swagger 1.2 and Swagger 2.0 specifications.
@@ -39,7 +43,9 @@ Looking to see how you can create your own OpenAPI definition, present it, or ot
 
 The current process for development of the OpenAPI Specification is described in 
 [Development Guidelines](DEVELOPMENT.md).
-Development of the next version of the OpenAPI Specification is guided by the [Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
+Development of the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master.
+
+The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the [TSC calendar online](https://oai-technicalsteeringcommittee.groups.io/g/main/calendar), and import it to your calendar using the [iCal link](https://OAI-TechnicalSteeringCommittee.groups.io/g/main/ics/860119/668774333/feed.ics).
 
 The Open API Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
 

examples/v2.0/yaml/petstore.yaml

@@ -28,7 +28,7 @@ paths:
           format: int32
       responses:
         "200":
-          description: An paged array of pets
+          description: A paged array of pets
           headers:
             x-next:
               type: string

examples/v3.0/api-with-examples.yaml

@@ -8,7 +8,7 @@ paths:
       operationId: listVersionsv2
       summary: List API versions
       responses:
-        200:
+        '200':
           description: |-
             200 response
           content:
@@ -41,7 +41,7 @@ paths:
                         }
                     ]
                  }
-        300:
+        '300':
           description: |-
             300 response
           content:
@@ -80,7 +80,7 @@ paths:
       operationId: getVersionDetailsv2
       summary: Show API version details
       responses:
-        200:
+        '200':
           description: |-
             200 response
           content:
@@ -125,7 +125,7 @@ paths:
                       ]
                     }
                   }
-        203:
+        '203':
           description: |-
             203 response
           content:

examples/v3.0/callback-example.yaml

@@ -1,4 +1,7 @@
-# ...
+openapi: 3.0.0
+info:
+  title: Callback Example
+  version: 1.0.0
 paths:
   /streams:
     post:

examples/v3.0/petstore-expanded.yaml

@@ -2,7 +2,7 @@ openapi: "3.0.0"
 info:
   version: 1.0.0
   title: Swagger Petstore
-  description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification
+  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
   termsOfService: http://swagger.io/terms/
   contact:
     name: Swagger API Team
@@ -40,7 +40,7 @@ paths:
             type: integer
             format: int32
       responses:
-        200:
+        '200':
           description: pet response
           content:
             application/json:
@@ -65,7 +65,7 @@ paths:
             schema:
               $ref: '#/components/schemas/NewPet'
       responses:
-        200:
+        '200':
           description: pet response
           content:
             application/json:
@@ -90,7 +90,7 @@ paths:
             type: integer
             format: int64
       responses:
-        200:
+        '200':
           description: pet response
           content:
             application/json:
@@ -114,7 +114,7 @@ paths:
             type: integer
             format: int64
       responses:
-        204:
+        '204':
           description: pet deleted
         default:
           description: unexpected error

examples/v3.0/petstore.yaml

@@ -22,7 +22,7 @@ paths:
             type: integer
             format: int32
       responses:
-        200:
+        '200':
           description: An paged array of pets
           headers:
             x-next:
@@ -45,7 +45,7 @@ paths:
       tags:
         - pets
       responses:
-        201:
+        '201':
           description: Null response
         default:
           description: unexpected error
@@ -67,7 +67,7 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        '200':
           description: Expected response to a valid request
           content:
             application/json:

examples/v3.0/uber.yaml

@@ -32,7 +32,7 @@ paths:
       tags: 
         - Products
       responses:  
-        200:
+        '200':
           description: An array of products
           content:
             application/json:
@@ -80,7 +80,7 @@ paths:
       tags: 
         - Estimates
       responses:  
-        200:
+        '200':
           description: An array of price estimates by product
           content:
             application/json:
@@ -127,7 +127,7 @@ paths:
       tags: 
         - Estimates
       responses:  
-        200:
+        '200':
           description: An array of products
           content:
             application/json:
@@ -148,7 +148,7 @@ paths:
       tags: 
         - User
       responses:
-        200:
+        '200':
           description: Profile information for a user
           content:
             application/json:
@@ -180,7 +180,7 @@ paths:
       tags: 
         - User
       responses:
-        200:
+        '200':
           description: History information for the given user
           content:
             application/json: