From 9bcc030c0ab80bc52e1a90b72a89d8bc6356c095 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Mar 2025 22:59:48 +0100 Subject: [PATCH 1/7] Delete schema.yaml --- schemas/v3.1/schema.yaml | 974 --------------------------------------- 1 file changed, 974 deletions(-) delete mode 100644 schemas/v3.1/schema.yaml diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml deleted file mode 100644 index ada84777fd..0000000000 --- a/schemas/v3.1/schema.yaml +++ /dev/null @@ -1,974 +0,0 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema/WORK-IN-PROGRESS' -$schema: 'https://json-schema.org/draft/2020-12/schema' - -description: The description of OpenAPI v3.1.x Documents without Schema Object validation - -type: object -properties: - openapi: - type: string - pattern: '^3\.1\.\d+(-.+)?$' - info: - $ref: '#/$defs/info' - jsonSchemaDialect: - type: string - format: uri-reference - default: 'https://spec.openapis.org/oas/3.1/dialect/WORK-IN-PROGRESS' - servers: - type: array - items: - $ref: '#/$defs/server' - default: - - url: / - paths: - $ref: '#/$defs/paths' - webhooks: - type: object - additionalProperties: - $ref: '#/$defs/path-item' - components: - $ref: '#/$defs/components' - security: - type: array - items: - $ref: '#/$defs/security-requirement' - tags: - type: array - items: - $ref: '#/$defs/tag' - externalDocs: - $ref: '#/$defs/external-documentation' -required: - - openapi - - info -anyOf: - - required: - - paths - - required: - - components - - required: - - webhooks -$ref: '#/$defs/specification-extensions' -unevaluatedProperties: false - -$defs: - info: - $comment: https://spec.openapis.org/oas/v3.1#info-object - type: object - properties: - title: - type: string - summary: - type: string - description: - type: string - termsOfService: - type: string - format: uri-reference - contact: - $ref: '#/$defs/contact' - license: - $ref: '#/$defs/license' - version: - type: string - required: - - title - - version - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - contact: - $comment: https://spec.openapis.org/oas/v3.1#contact-object - type: object - properties: - name: - type: string - url: - type: string - format: uri-reference - email: - type: string - format: email - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - license: - $comment: https://spec.openapis.org/oas/v3.1#license-object - type: object - properties: - name: - type: string - identifier: - type: string - url: - type: string - format: uri-reference - required: - - name - dependentSchemas: - identifier: - not: - required: - - url - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - server: - $comment: https://spec.openapis.org/oas/v3.1#server-object - type: object - properties: - url: - type: string - description: - type: string - variables: - type: object - additionalProperties: - $ref: '#/$defs/server-variable' - required: - - url - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - server-variable: - $comment: https://spec.openapis.org/oas/v3.1#server-variable-object - type: object - properties: - enum: - type: array - items: - type: string - minItems: 1 - default: - type: string - description: - type: string - required: - - default - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - components: - $comment: https://spec.openapis.org/oas/v3.1#components-object - type: object - properties: - schemas: - type: object - additionalProperties: - $dynamicRef: '#meta' - responses: - type: object - additionalProperties: - $ref: '#/$defs/response-or-reference' - parameters: - type: object - additionalProperties: - $ref: '#/$defs/parameter-or-reference' - examples: - type: object - additionalProperties: - $ref: '#/$defs/example-or-reference' - requestBodies: - type: object - additionalProperties: - $ref: '#/$defs/request-body-or-reference' - headers: - type: object - additionalProperties: - $ref: '#/$defs/header-or-reference' - securitySchemes: - type: object - additionalProperties: - $ref: '#/$defs/security-scheme-or-reference' - links: - type: object - additionalProperties: - $ref: '#/$defs/link-or-reference' - callbacks: - type: object - additionalProperties: - $ref: '#/$defs/callbacks-or-reference' - pathItems: - type: object - additionalProperties: - $ref: '#/$defs/path-item' - patternProperties: - '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$': - $comment: Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected - propertyNames: - pattern: '^[a-zA-Z0-9._-]+$' - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - paths: - $comment: https://spec.openapis.org/oas/v3.1#paths-object - type: object - patternProperties: - '^/': - $ref: '#/$defs/path-item' - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - path-item: - $comment: https://spec.openapis.org/oas/v3.1#path-item-object - type: object - properties: - $ref: - type: string - format: uri-reference - summary: - type: string - description: - type: string - servers: - type: array - items: - $ref: '#/$defs/server' - parameters: - type: array - items: - $ref: '#/$defs/parameter-or-reference' - get: - $ref: '#/$defs/operation' - put: - $ref: '#/$defs/operation' - post: - $ref: '#/$defs/operation' - delete: - $ref: '#/$defs/operation' - options: - $ref: '#/$defs/operation' - head: - $ref: '#/$defs/operation' - patch: - $ref: '#/$defs/operation' - trace: - $ref: '#/$defs/operation' - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - operation: - $comment: https://spec.openapis.org/oas/v3.1#operation-object - type: object - properties: - tags: - type: array - items: - type: string - summary: - type: string - description: - type: string - externalDocs: - $ref: '#/$defs/external-documentation' - operationId: - type: string - parameters: - type: array - items: - $ref: '#/$defs/parameter-or-reference' - requestBody: - $ref: '#/$defs/request-body-or-reference' - responses: - $ref: '#/$defs/responses' - callbacks: - type: object - additionalProperties: - $ref: '#/$defs/callbacks-or-reference' - deprecated: - default: false - type: boolean - security: - type: array - items: - $ref: '#/$defs/security-requirement' - servers: - type: array - items: - $ref: '#/$defs/server' - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - external-documentation: - $comment: https://spec.openapis.org/oas/v3.1#external-documentation-object - type: object - properties: - description: - type: string - url: - type: string - format: uri-reference - required: - - url - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - parameter: - $comment: https://spec.openapis.org/oas/v3.1#parameter-object - type: object - properties: - name: - type: string - in: - enum: - - query - - header - - path - - cookie - description: - type: string - required: - default: false - type: boolean - deprecated: - default: false - type: boolean - schema: - $dynamicRef: '#meta' - content: - $ref: '#/$defs/content' - minProperties: 1 - maxProperties: 1 - required: - - name - - in - oneOf: - - required: - - schema - - required: - - content - if: - properties: - in: - const: query - required: - - in - then: - properties: - allowEmptyValue: - default: false - type: boolean - dependentSchemas: - schema: - properties: - style: - type: string - explode: - type: boolean - allOf: - - $ref: '#/$defs/examples' - - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path' - - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header' - - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query' - - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie' - - $ref: '#/$defs/styles-for-form' - - $defs: - styles-for-path: - if: - properties: - in: - const: path - required: - - in - then: - properties: - style: - default: simple - enum: - - matrix - - label - - simple - required: - const: true - required: - - required - - styles-for-header: - if: - properties: - in: - const: header - required: - - in - then: - properties: - style: - default: simple - const: simple - - styles-for-query: - if: - properties: - in: - const: query - required: - - in - then: - properties: - style: - default: form - enum: - - form - - spaceDelimited - - pipeDelimited - - deepObject - allowReserved: - default: false - type: boolean - - styles-for-cookie: - if: - properties: - in: - const: cookie - required: - - in - then: - properties: - style: - default: form - const: form - - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - parameter-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/parameter' - - request-body: - $comment: https://spec.openapis.org/oas/v3.1#request-body-object - type: object - properties: - description: - type: string - content: - $ref: '#/$defs/content' - required: - default: false - type: boolean - required: - - content - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - request-body-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/request-body' - - content: - $comment: https://spec.openapis.org/oas/v3.1#fixed-fields-10 - type: object - additionalProperties: - $ref: '#/$defs/media-type' - propertyNames: - format: media-range - - media-type: - $comment: https://spec.openapis.org/oas/v3.1#media-type-object - type: object - properties: - schema: - $dynamicRef: '#meta' - encoding: - type: object - additionalProperties: - $ref: '#/$defs/encoding' - allOf: - - $ref: '#/$defs/specification-extensions' - - $ref: '#/$defs/examples' - unevaluatedProperties: false - - encoding: - $comment: https://spec.openapis.org/oas/v3.1#encoding-object - type: object - properties: - contentType: - type: string - format: media-range - headers: - type: object - additionalProperties: - $ref: '#/$defs/header-or-reference' - style: - default: form - enum: - - form - - spaceDelimited - - pipeDelimited - - deepObject - explode: - type: boolean - allowReserved: - default: false - type: boolean - allOf: - - $ref: '#/$defs/specification-extensions' - - $ref: '#/$defs/styles-for-form' - unevaluatedProperties: false - - responses: - $comment: https://spec.openapis.org/oas/v3.1#responses-object - type: object - properties: - default: - $ref: '#/$defs/response-or-reference' - patternProperties: - '^[1-5](?:[0-9]{2}|XX)$': - $ref: '#/$defs/response-or-reference' - minProperties: 1 - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - if: - $comment: either default, or at least one response code property must exist - patternProperties: - '^[1-5](?:[0-9]{2}|XX)$': false - then: - required: [default] - - response: - $comment: https://spec.openapis.org/oas/v3.1#response-object - type: object - properties: - description: - type: string - headers: - type: object - additionalProperties: - $ref: '#/$defs/header-or-reference' - content: - $ref: '#/$defs/content' - links: - type: object - additionalProperties: - $ref: '#/$defs/link-or-reference' - required: - - description - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - response-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/response' - - callbacks: - $comment: https://spec.openapis.org/oas/v3.1#callback-object - type: object - $ref: '#/$defs/specification-extensions' - additionalProperties: - $ref: '#/$defs/path-item' - - callbacks-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/callbacks' - - example: - $comment: https://spec.openapis.org/oas/v3.1#example-object - type: object - properties: - summary: - type: string - description: - type: string - value: true - externalValue: - type: string - format: uri-reference - not: - required: - - value - - externalValue - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - example-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/example' - - link: - $comment: https://spec.openapis.org/oas/v3.1#link-object - type: object - properties: - operationRef: - type: string - format: uri-reference - operationId: - type: string - parameters: - $ref: '#/$defs/map-of-strings' - requestBody: true - description: - type: string - body: - $ref: '#/$defs/server' - oneOf: - - required: - - operationRef - - required: - - operationId - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - link-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/link' - - header: - $comment: https://spec.openapis.org/oas/v3.1#header-object - type: object - properties: - description: - type: string - required: - default: false - type: boolean - deprecated: - default: false - type: boolean - schema: - $dynamicRef: '#meta' - content: - $ref: '#/$defs/content' - minProperties: 1 - maxProperties: 1 - oneOf: - - required: - - schema - - required: - - content - dependentSchemas: - schema: - properties: - style: - default: simple - const: simple - explode: - default: false - type: boolean - $ref: '#/$defs/examples' - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - header-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/header' - - tag: - $comment: https://spec.openapis.org/oas/v3.1#tag-object - type: object - properties: - name: - type: string - description: - type: string - externalDocs: - $ref: '#/$defs/external-documentation' - required: - - name - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - reference: - $comment: https://spec.openapis.org/oas/v3.1#reference-object - type: object - properties: - $ref: - type: string - format: uri-reference - summary: - type: string - description: - type: string - - schema: - $comment: https://spec.openapis.org/oas/v3.1#schema-object - $dynamicAnchor: meta - type: - - object - - boolean - - security-scheme: - $comment: https://spec.openapis.org/oas/v3.1#security-scheme-object - type: object - properties: - type: - enum: - - apiKey - - http - - mutualTLS - - oauth2 - - openIdConnect - description: - type: string - required: - - type - allOf: - - $ref: '#/$defs/specification-extensions' - - $ref: '#/$defs/security-scheme/$defs/type-apikey' - - $ref: '#/$defs/security-scheme/$defs/type-http' - - $ref: '#/$defs/security-scheme/$defs/type-http-bearer' - - $ref: '#/$defs/security-scheme/$defs/type-oauth2' - - $ref: '#/$defs/security-scheme/$defs/type-oidc' - unevaluatedProperties: false - - $defs: - type-apikey: - if: - properties: - type: - const: apiKey - required: - - type - then: - properties: - name: - type: string - in: - enum: - - query - - header - - cookie - required: - - name - - in - - type-http: - if: - properties: - type: - const: http - required: - - type - then: - properties: - scheme: - type: string - required: - - scheme - - type-http-bearer: - if: - properties: - type: - const: http - scheme: - type: string - pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$ - required: - - type - - scheme - then: - properties: - bearerFormat: - type: string - - type-oauth2: - if: - properties: - type: - const: oauth2 - required: - - type - then: - properties: - flows: - $ref: '#/$defs/oauth-flows' - required: - - flows - - type-oidc: - if: - properties: - type: - const: openIdConnect - required: - - type - then: - properties: - openIdConnectUrl: - type: string - format: uri-reference - required: - - openIdConnectUrl - - security-scheme-or-reference: - if: - type: object - required: - - $ref - then: - $ref: '#/$defs/reference' - else: - $ref: '#/$defs/security-scheme' - - oauth-flows: - type: object - properties: - implicit: - $ref: '#/$defs/oauth-flows/$defs/implicit' - password: - $ref: '#/$defs/oauth-flows/$defs/password' - clientCredentials: - $ref: '#/$defs/oauth-flows/$defs/client-credentials' - authorizationCode: - $ref: '#/$defs/oauth-flows/$defs/authorization-code' - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - $defs: - implicit: - type: object - properties: - authorizationUrl: - type: string - format: uri-reference - refreshUrl: - type: string - format: uri-reference - scopes: - $ref: '#/$defs/map-of-strings' - required: - - authorizationUrl - - scopes - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - password: - type: object - properties: - tokenUrl: - type: string - format: uri-reference - refreshUrl: - type: string - format: uri-reference - scopes: - $ref: '#/$defs/map-of-strings' - required: - - tokenUrl - - scopes - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - client-credentials: - type: object - properties: - tokenUrl: - type: string - format: uri-reference - refreshUrl: - type: string - format: uri-reference - scopes: - $ref: '#/$defs/map-of-strings' - required: - - tokenUrl - - scopes - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - authorization-code: - type: object - properties: - authorizationUrl: - type: string - format: uri-reference - tokenUrl: - type: string - format: uri-reference - refreshUrl: - type: string - format: uri-reference - scopes: - $ref: '#/$defs/map-of-strings' - required: - - authorizationUrl - - tokenUrl - - scopes - $ref: '#/$defs/specification-extensions' - unevaluatedProperties: false - - security-requirement: - $comment: https://spec.openapis.org/oas/v3.1#security-requirement-object - type: object - additionalProperties: - type: array - items: - type: string - - specification-extensions: - $comment: https://spec.openapis.org/oas/v3.1#specification-extensions - patternProperties: - '^x-': true - - examples: - properties: - example: true - examples: - type: object - additionalProperties: - $ref: '#/$defs/example-or-reference' - - map-of-strings: - type: object - additionalProperties: - type: string - - styles-for-form: - if: - properties: - style: - const: form - required: - - style - then: - properties: - explode: - default: true - else: - properties: - explode: - default: false From 3b45fd44421a618449a9094edf2269c5693de134 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Mar 2025 23:01:20 +0100 Subject: [PATCH 2/7] Update CONTRIBUTING.md --- CONTRIBUTING.md | 491 ++++++++++++++++++++++++++++++------------------ 1 file changed, 309 insertions(+), 182 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b48f0096bc..8d243b0104 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,59 +1,333 @@ -# Contributing to the OpenAPI Specification +# Contribute to the OpenAPI Specification -***Work in progress!** Each section links to issues that are relevant to fill out the rest of this document.* +## Key information -We are currently working on [defining and documenting our new processes](https://github.com/orgs/OAI/projects/5). Information in this document is up-to-date. Older _(and sometimes now inaccurate)_ documentation can be found in [DEVELOPMENT.md](DEVELOPMENT.md), which will be removed when everything is updated and documented here. +This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme). +All participants are expected to read and follow this code. -## Essential Policies +No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder). +Exceptions may be made when links to external URLs have been changed by a 3rd party, in order to keep our documents accurate. -This section serves as a quick guide while we work on the full updated documentation. +Published versions of the specification are in the `versions/` folder. +The under-development versions of the specification are in the file `src/oas.md` on the appropriately-versioned branch. +For example, work on the next release for 3.2 is on `v3.2-dev` in the file `src/oas.md`. -If in doubt about a policy, please [ask on our Slack](https://communityinviter.com/apps/open-api/openapi) before opening a PR. +The [spec site](https://spec.openapis.org) is the source of truth for the OpenAPI specification as it contains all the citations and author credits (the markdown in this repository was previously the authoritative version until 2024). -### No changes to published specifications +The OpenAPI project is almost entirely staffed by volunteers. +Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world. -No changes, ***no matter how trivial***, are ever made to the contents of published specifications. The only potential changes to those documents are updates to link URLs _if and only if_ the targeted document is moved by a 3rd party. Other changes to link URLs are not allowed. +### Active branches -### Authoritative source of truth +The current active specification releases are: -The [spec site](https://spec.openapis.org) is the source of truth. +| Version | Branch | Notes | +| ------- | ------ | ----- | +| 3.1.2 | `v3.1-dev` | active patch release line | +| 3.2.0 | `v3.2-dev` | minor release in development | +| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | -This changed in 2024, as the markdown files on `main` do not include certain credits and citations. -## Development process +## How to contribute -As of October 2024 (post-OAS 3.0.4 and 3.1.1), the OAS is developed in the `src/oas.md` file on minor release `vX.Y-dev` branches that are derived from the baseline `dev` branch. +We welcome new contributors to the project whether you have changes to suggest, problems to report, or some feedback for us. +Please jump to the most relevant section from the list below: -Schema changes are made on the same branch, but can be released independently. When making a specification change for a new minor or major release that has a schema impact, including the schema change in the PR is preferred. Patch releases cannot contain changes that _require_ a schema update. +- Ask a question or offer feedback: use a [discussion](#discussions) +- Suggest a change or report a problem: open an [issue](#issues) +- Contribute a change to the repository: open a [pull request](#pull-requests) +- Or just [get in touch](#get-in-touch) -### Branch roles +## Discussions -* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed. The `src` tree is ***not*** present on `main`. -* `dev` is the primary branch for working with the `src` tree, which is kept up-to-date with the most recent release on the most recent minor (X.Y) release line, and serves as the base for each new minor release line. Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed. -* `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions. All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document. -* `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0). It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links. +We use [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for anything that doesn't (yet) have a specific action associated with it. +Most ideas start as discussions. + +Please do come and start a discussion to: + + - ask questions + - make suggestions + - give feedback + +Anyone can start a discussion and you're very welcome to do so! Write a message and pick a relevant discussion category. + +### Discussion management + +Participation in discussions and especially answering of questions is encouraged (and appreciated) by everyone. + +Discussions are closed when: + + - the question has been answered. + - no further action or conversation would be useful. + - there has been no engagement for a while, or a previously popular thread has been inactive for an extended period. + - activity is now taking place elsewhere, such as in an issue. + - the discussion is out of scope for the project. + +## Issues + +Issues are for planned tasks, problems to solve, or requests for (specific) changes. +Most issues should have a clear outcome; something will be fixed, improved or otherwise measurably different when the issue is complete. + +We use [discussions](#discussions) for ideas and early-stage suggestions. + +> [!NOTE] +> For larger or more extensive changes, we have a formal [proposal process](#propose-a-specification-change) to give more structure where it's needed. + +The best issues give a clear and concise explanation of the problem at hand, and ideally some examples of what the problem is. +Suggested solutions are also welcome, but it is very important that the issue outlines the problem that is being solved as well as the solution. +Some issues may be a backlog of a task that needs to be done; other issues might be automatically created as part of the project processes. + +### Issue management + +We have some issue automation to close inactive issues and create/pin/archive the weekly meeting issues. +More information is in the [Appendix: Issue automation](#appendix-issue-automation) section. + +Everyone is encouraged to open and comment on issues in the project. +If you want to tag/assign/close something and you don't have enough permissions, add a comment and someone will help. + +Issues are managed by the [Triage](#triage), [Maintainers](#maintainers) and [TSC](#tsc) teams. +They may move issues to other repositories within the project as needed. + +In order to keep the issues list manageable and realistic for a relatively small group of volunteers, issues are proactively closed when it's not clear that they can be completed. +Issues may be closed when: + +- they have been inactive for a long time +- they are out of scope or no further constructive action can be taken +- they are complete (yay!) +- they are unclear and more details are not forthcoming +- as a group, there is agreement that no further action will be taken + +When issues are closed, a comment is added about why. +Closing issues is a reversible action, and it is always acceptable to comment and explain (politely) why an issue should not have been closed. + +### Labels + +We make extensive use of labels. +The main categories are: + +- [Housekeeping](https://github.com/OAI/OpenAPI-Specification/labels/Housekeeping) for meetings, project logistics, etc. +- [approved pr port](https://github.com/OAI/OpenAPI-Specification/labels/approved%20pr%20port) for pull requests that repeat a change from one version to another +- most other tags are used to group similar or related issues into topic areas; this list is ever-changing + +Labels related to [issue automation](#appendix-issue-automation) + +- [Needs attention](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20attention) automated tag when an issue is updated +- [Needs author feedback](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20author%20feedback) used to indicate that more information is needed from the issue creator +- [No recent activity](https://github.com/OAI/OpenAPI-Specification/labels/No%20recent%20activity) if no information is received, the issue is marked for closure (automatic after 30 days) + +### Milestones + +We use milestones in GitHub to plan what should be included in future releases. +Issues and pull requests should both be added to the earliest milestone we expect they will be released in. +Any changes that aren't ready in time for release should be moved to the next milestone or untagged. + +The milestones and items assigned to them are under constant review and subject to change. + +### Projects + +The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the specification development process. There are currently two active projects: + +* [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1) +* [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1) + +## Pull requests + +> [!NOTE] +> Since the 3.0.4 and 3.1.1 releases (October 2024), the OAS is developed in the `src/oas.md` file. +> Check the [Appendix: Branch Strategy](#appendix-branch-strategy) for more information about the updated branching strategy. + +Changes to the next version of the specification are welcome and can be proposed by anyone. + +For large changes that will need discussion, please use the [Proposal process](#propose-a-specification-change). +For other changes, we recommend [opening an issue](#issues) first, so that you can get some feedback and any extra input you need before spending a lot of time on something. + +Schema changes are made on the same branch, but can be released independently. +When making a specification change for a new minor or major release that has a schema impact, including the schema change in the PR is preferred. +Patch releases cannot contain changes that _require_ a schema update. + +### Use a fork + +All work **MUST be done on a fork** and be submitted as a pull request. + +### Target the earliest active `*-dev` branch + +Branch from and submit pull requests to the a branch from the _earliest relevant and [active](#active-branches)_ `vX.Y-dev` branch. +For example, if a change applies to both 3.1 and 3.2, the PR would go to the `v3.1-dev` branch, which will be merged up to `v3.2-dev` before the next 3.2 release. +All changes to the specification must conform to the [style guide](./style-guide.md). + +Both specification and schema changes follow this approach. + +For changes to repository files that affect all versions, use the `main` branch. +This might apply to, for example, Markdown files, automation, and scripts. + +For all pull requests, if they should not be merged yet for any reason (they depend on something else, you would like feedback from a specific reviewer), mark them as draft and they will not be merged while in that state. +Draft pull requests can still be reviewed while in draft state. + +### Preview specification HTML locally + +The markdown source files are converted to HTML before publishing. +To do this locally, please + +1. Install [Node.js](https://nodejs.org/) +2. Check out this repo, go to the repo root, and switch to a development branch +3. Execute `npm install` (once, repeat after merging upstream changes) +4. Execute `npm run build-src` after changing `src/oas.md` (this first executes `npm run validate-markdown`, which can also be run separately) +5. Open output file `deploy-preview/oas.html` with a browser and check your changes + +Please make sure the markdown validates and builds using the above steps before creating a pull request or marking a draft pull request as ready for review. + +## Reviewers + +> [!NOTE] +> See also the detailed team outlines in the [roles section](#roles). -### Using forks +All pull requests must be reviewed and approved by one member of the TSC or Maintainers teams. +Reviews from other contributors are always welcome. -All work **MUST be done on a fork**, using a branch from the _earliest relevant and [active](#active-branches)_ `vX.Y-dev` branch, and then submitted as a PR to that `vX.Y-dev` branch. -For example, if a change in November 2024 apples to both 3.1 and 3.2, the PR would go to the `v3.1-dev` branch, which will be merged up to `v3.2-dev` before the next 3.2 release. +Additionally, all pull requests that change the specification file `src/oas.md` must be approved by two TSC members. + +Reviews requesting changes should have their changes addressed regardless of how many other approvers there are. ## Publishing -The specification and schemas are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`. The HTML versions of the OAS are automatically generated from the `versions` directory on `main`. This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files). +### Specification Versions + +The specification versions are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`. +This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files). + +The HTML renderings of the specification versions are automatically generated from the `versions` directory on `main` by the [`respec` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml), which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org). + +### Schema Iterations + +The schema iterations are published independently from the specification releases [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas). +Schemas are updated in and directly published from the `vX.Y-dev` branches. + +As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is usually done by the `schema-publish` workflow which detects changes on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). The workflow can also be run manually if required. + +## Release Process and Scope + +This section relates to the 3.x versions only. + +### Minor Releases + +Our roadmap for 3.x releases is community-driven, meaning the specification is open for proposed additions by anyone (see [Propose a Specification Change](#propose-a-specification-change)), in addition to the issues already on the project backlog. + +Changes in minor releases (such as 3.2, 3.3) meet the following criteria: + +* Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version. + For example, new optional fields can be added. +* Drive quality-of-life improvements to support how OpenAPI is used by practitioners, so that OpenAPI evolves to continue to meet user needs. + For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification. +* Bring the future closer by making changes that are in line with future 3.x releases and the planned OpenAPI 4.x (Moonwalk) specification as the details of that become available. +* Make the specification document clearer or easier to understand. + +A minor release is due when there are some meaningful features (including one or a small number of headline features). + +### Patch Releases + +Patch releases reflect a constant quest for improving the active minor versions of OpenAPI. +Since we do not edit specification documents after publication, even the smallest change has to be in a new release. + +Changes in patch releases meet the following criteria: + +* Editorial changes such as spelling or formatting fixes, including link updates. +* Clarifications or additions that do not change the meaning of the specification. + +Patch releases are created as often as there are changes to the specification worth releasing. + +### Release Process + +A release requires a vote on the specification at a particular version and the associated release notes by TSC members within the voting period. +Major or minor release voting periods will be announced in the Slack channel and noted on the calendar at least 6 days in advance. +During this time, TSC members who have not yet voted must note their approval by leaving a comment on the GitHub pull request proposing the release; release notes should be included with the description. +TSC members are responsible for coordinating the information about the release to the outreach team as appropriate. + +* Patch-level releases require majority approval by TSC members. (Max voting period 3 days) + +* Minor: requires approval by 66% of TSC members. (Max voting period 7 days) + +* Major: requires approval by 66% of TSC members. (Max voting period 14 days) + +During the voting period, further changes should not be made to the specification being considered. + +Once the threshold of approvals is met, the release can be performed by any TSC member. + +## Propose a Specification Change + +As an organisation, we're open to changes, and these can be proposed by anyone. +The specification is very widely adopted, and there is an appropriately high bar for wide appeal and due scrutiny as a result. +We do not accept changes lightly (but we will consider any that we can). + +Small changes are welcome as pull requests. + +Bigger changes require a more formal process. + +1. Start a [discussion](https://github.com/OAI/OpenAPI-Specification/discussions) of type "Enhancements". + The discussion entry must include some use cases, your proposed solution and the alternatives you have considered. + If there is engagement and support for the proposal over time, then it can be considered as a candidate to move to the next stage. + +2. It really helps to see the proposed change in action. + Start using it as a `x-*` extension if that's appropriate, or try to bring other evidence of your proposed solution being adopted. + +3. If you are adding support for something from another specification (such as OAuth), please point to implementations of that + specification so that we can understand how, and to what degree, it is being used. + +4. If the suggested change has good support, you will be asked to create a formal proposal. + Use the [template in the proposals directory](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals), copy it to a new file, and complete it. + Once you the document is ready, open a pull request on the main branch. + +5. The proposal will be more closely reviewed and commented on or amended until it is either rejected or accepted. + At that point, the proposal is merged into the `main` branch and a pull request is opened to add the feature to the appropriate `dev` version of the specification. + +Questions are welcome on the process at any time. Use the discussions feature or find us in Slack. + +## Roles + +The OpenAPI project has some key roles that are played by multiple people. + +### TSC + +The Technical Steering Committee are listed in the [MAINTAINERS file](./MAINTAINERS.md). +They are the maintainers of the OpenAPI Specification itself and every other aspect of the project operation and direction. +TSC members can review changes to all parts of the repository and make decisions about the project. + +### Maintainers + +The maintainers have write access to the repository and play a key role in the project. +They review pull requests to non-specification parts of the repository, and take on other strategic tasks around project planning and maintenance. + +### Triage -The publishing process for schemas is still under discussion (see issues [#3715](https://github.com/OAI/OpenAPI-Specification/issues/3715) and [#3716](https://github.com/OAI/OpenAPI-Specification/issues/3716)), with the current proposal being to release them directly from the `vX.Y-dev` branch without merging to `main`, as the schemas in source control have placeholder identifiers and are not intended to be used as-is. +The triage team are active OpenAPI members who help with discussion and issue management. +They respond to new issues and discussions, direct people to our existing resources or raise conversations to a wider audience. +The triage team keeps an eye on the backlog and closes issues and discussions that are no longer active or needed. -### Historical branch strategy +## Get in touch + +To get in touch with other people on the project, ask questions, or anything else: + +- Find us [on the OpenAPI Slack](https://communityinviter.com/apps/open-api/openapi). +- Start a [GitHub Discussion](https://github.com/OAI/OpenAPI-Specification/discussions/). +- Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHousekeeping). + +## Appendix: Branch strategy For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and earlier, see the comments in [issue #3677](https://github.com/OAI/OpenAPI-Specification/issues/3677). +### Branch roles + +* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed. The `src` tree is ***not*** present on `main`. +* `dev` is the primary branch for working with the `src` tree, which is kept up-to-date with the most recent release on the most recent minor (X.Y) release line, and serves as the base for each new minor release line. Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed. + Changes on `main` are automatically included in a pull request to `dev` (see the (section on [branch sync](#branch-sync-automation)). +* `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions. All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document. +* `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0). It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links. + ### Branching and merging (3.1.2, 3.2.0, and later) Upon release: * Pre-release steps: - * The most recent _published_ patch release from the previoius line is merged up to `vX.Y-dev`, if relevant + * The most recent _published_ patch release from the previous line is merged up to `vX.Y-dev`, if relevant * If doing simultaneous releases on multiple lines, do them from the oldest to newest line * If the release is the most recent on the current line, merge `vX.Y-dev` to `dev` * For example, if releasing 3.1.3 and 3.2.0: @@ -163,155 +437,18 @@ gitGraph TB: commit id:"3.3 work" ``` -#### Active branches - -The first PR for a change should be against the oldest release line to which it applies. Changes can then be forward-ported as appropriate. - -The specification under development is `src/oas.md`, which _only_ exists on development branches, not on `main`. - -The current (20 October 2024) active specification releases are: - -| Version | Branch | Notes | -| ------- | ------ | ----- | -| 3.1.2 | `v3.1-dev` | active patch release line | -| 3.2.0 | `v3.2-dev` | minor release in development | -| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | - -## Style Guide - -Contributions to this repository should follow the style guide as described in this section. - -### Markdown - -Markdown files in this project should follow the style enforced by the [markdownlint tool](https://www.npmjs.com/package/markdownlint), -as configured by the `.markdownlint.yaml` file in the root of the project. -The `markdownlint` tool can also fix formatting, which can save time with tables in particular. - -The following additional rules should be followed but currently are not enforced by tooling: - -1. The first mention of a normative reference or an OAS-defined Object in a (sub)*section is a link, additional mentions are not. -2. OAS-defined Objects such as Schema Objects are written in this style, and are not monospaced. -3. Use "example" instead of "sample" - this spec is not about statistics. -4. Use "OpenAPI Object" instead of "root". -5. Fixed fields are monospaced. -6. Field values are monospaced in JSON notation: `true`, `false`, `null`, `"header"` (with double-quotes around string values). -7. A combination of fixed field name with example value uses JS notation: `in: "header"`, combining rules 5 and 6. -8. An exception to 5-7 is colloquial use, for example "values of type `array` or `object`" - "type" is not monospaced, so the monospaced values aren't enclosed in double quotes. -9. Use Oxford commas, avoid Shatner commas. -10. Use `` for link anchors. The `` format has been deprecated. -11. Headings use [title case](https://en.wikipedia.org/wiki/Title_case) and are followed by a blank line. - -Plus some suggestions, rather than rules: - -* Use one sentence per line in paragraphs and bullet points, to make diffs and edits easier to compare and understand. - A blank line is needed to cause a paragraph break in Markdown. -* In examples, use realistic values rather than foo/bar. - -### Use of "keyword", "field", "property", and "attribute" - -* JSON Schema keywords -> "keyword" -* OpenAPI fixed fields -> "field" -* property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property" -* "attribute" is only used in the XML context and means "XML attribute" - -### Field Names and Values in YAML comments - -Field names and keywords should be in backticks. -Values like "Dog" should be double quoted. - -## Release Process and Scope - -This section relates to the 3.x versions only. - -### Minor Releases - -Our roadmap for 3.x releases is community-driven, meaning the specification is open for proposed additions by anyone (see [Proposals for Specification Changes](#proposals-for-specification-changes)), in addition to the issues already on the project backlog. - -Changes in minor releases (such as 3.2, 3.3) meet the following criteria: - -* Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version. - For example, new optional fields can be added. -* Drive quality-of-life improvements to support how OpenAPI is used by practitioners, so that OpenAPI evolves to continue to meet user needs. - For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification. -* Bring the future closer by making changes that are in line with future 3.x releases and the planned OpenAPI 4.x (Moonwalk) specification as the details of that become available. -* Make the specification document clearer or easier to understand. - -A minor release is due when there are some meaningful features (including one or a small number of headline features). - -### Patch Releases - -Patch releases reflect a constant quest for improving the active minor versions of OpenAPI. -Since we do not edit specification documents after publication, even the smallest change has to be in a new release. - -Changes in patch releases meet the following criteria: - -* Editorial changes such as spelling or formatting fixes, including link updates. -* Clarifications or additions that do not change the meaning of the specification. - -Patch releases are created as often as there are changes to the specification worth releasing. - -## Branching and Versioning - -* Issue #3677: [Define and document branch strategy for the spec, both development and publishing](https://github.com/OAI/OpenAPI-Specification/issues/3677) - -## Proposals for Specification Changes - -As an organisation, we're open to changes, and these can be proposed by anyone. -The specification is very widely adopted, and there is an appropriately high bar for wide appeal and due scrutiny as a result. -We do not accept changes lightly (but we will consider any that we can). - -Small changes are welcome as pull requests. - -Bigger changes require a more formal process. - -1. Start a [discussion](https://github.com/OAI/OpenAPI-Specification/discussions) of type "Enhancements". - The discussion entry must include some use cases, your proposed solution and the alternatives you have considered. - If there is engagement and support for the proposal over time, then it can be considered as a candidate to move to the next stage. - -2. It really helps to see the proposed change in action. - Start using it as a `x-*` extension if that's appropriate, or try to bring other evidence of your proposed solution being adopted. - -3. If you are adding support for something from another specification (such as OAuth), please point to implementations of that - specification so that we can understand how, and to what degree, it is being used. - -4. If the suggested change has good support, you will be asked to create a formal proposal. - Use the [template in the proposals directory](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals), copy it to a new file, and complete it. - Once you the document is ready, open a pull request on the main branch. - -5. The proposal will be more closely reviewed and commented on or amended until it is either rejected or accepted. - At that point, the proposal is merged into the `main` branch and a pull request is opened to add the feature to the appropriate `dev` version of the specification. +### Branch sync automation -Questions are welcome on the process at any time. Use the discussions feature or find us in Slack. - -## Working in GitHub +To keep changes in sync, we have some GitHub actions that open pull requests to take changes from `main` onto the `dev` branch, and from `dev` to each active version branch. -* Issue #3847: [Document milestone usage in DEVELOPMENT.md](https://github.com/OAI/OpenAPI-Specification/issues/3847) -* Issue #3848: [Define and add new process labels and document general label usage in DEVELOPMENT.md](https://github.com/OAI/OpenAPI-Specification/issues/3848) +- `sync-main-to-dev` opens a pull request with all the changes from the `main` branch that aren't yet included on `dev`. +- `sync-dev-to-vX.Y-dev` opens pull requests with all the changes from `dev` that aren't yet included on the corresponding `vX.Y-dev` branch. -### Roles and Permissions +These need a single approval from either maintainers or TSC and can be merged. +The aim is to bring build script and repository documentation changes to the other branches. +Published versions of the specifications and schemas will also move across branches with this approach. -* Issue #3582: [TOB info needs to be updated](https://github.com/OAI/OpenAPI-Specification/issues/3482) -* Issue #3523: [Define triage role criteria and process](https://github.com/OAI/OpenAPI-Specification/issues/3523) -* Issue #3524: [Define the maintainer role criteria and process](https://github.com/OAI/OpenAPI-Specification/issues/3524) - -### Projects - -The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the specification development process. There are currently two active projects: - -* [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1) -* [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1) - -### Discussions - -We are beginning (as of mid-2024) to use GitHub [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for open-ended topics such as major enhancements. - -* Issue #3518: [Define criteria for filing/closing issues vs discussions](https://github.com/OAI/OpenAPI-Specification/issues/3518) - -### Issues - -As of mid-2024, we prefer to use issues for topics that have a clear associated action. However, many existing issues are more open-ended, as they predate GitHub's discussions features. - -* Issue #3518: [Define criteria for filing/closing issues vs discussions](https://github.com/OAI/OpenAPI-Specification/issues/3518) +## Appendix: Issue Automation ### Automated closure of issues Process @@ -327,14 +464,4 @@ This process makes use of the following labels: An issue is opened every week, 7 days in advance, for the Technical Developer Community (TDC), it provides the information to connect the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping". -Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. - -## Pull Requests - -* Issue #3581: [Who and how many people need to sign-off on a PR, exactly?](https://github.com/OAI/OpenAPI-Specification/issues/3581) -* Issue #3802: [Define a policy using draft PRs when waiting on specific approvals](https://github.com/OAI/OpenAPI-Specification/issues/3802) - -## Updating the Registries - -* Issue #3598: [Minimum criteria for Namespace Registry](https://github.com/OAI/OpenAPI-Specification/issues/3598) -* Issue #3899: [Expert review criteria for registries (How exactly does x-twitter work?)](https://github.com/OAI/OpenAPI-Specification/issues/3899) +Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. \ No newline at end of file From ca0b2f790ace7bf34a299b7b5fc899e53d6ecabb Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Mar 2025 23:02:57 +0100 Subject: [PATCH 3/7] Revert "Update CONTRIBUTING.md" This reverts commit 3b45fd44421a618449a9094edf2269c5693de134. --- CONTRIBUTING.md | 491 ++++++++++++++++++------------------------------ 1 file changed, 182 insertions(+), 309 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d243b0104..b48f0096bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,333 +1,59 @@ -# Contribute to the OpenAPI Specification +# Contributing to the OpenAPI Specification -## Key information +***Work in progress!** Each section links to issues that are relevant to fill out the rest of this document.* -This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme). -All participants are expected to read and follow this code. +We are currently working on [defining and documenting our new processes](https://github.com/orgs/OAI/projects/5). Information in this document is up-to-date. Older _(and sometimes now inaccurate)_ documentation can be found in [DEVELOPMENT.md](DEVELOPMENT.md), which will be removed when everything is updated and documented here. -No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder). -Exceptions may be made when links to external URLs have been changed by a 3rd party, in order to keep our documents accurate. +## Essential Policies -Published versions of the specification are in the `versions/` folder. -The under-development versions of the specification are in the file `src/oas.md` on the appropriately-versioned branch. -For example, work on the next release for 3.2 is on `v3.2-dev` in the file `src/oas.md`. +This section serves as a quick guide while we work on the full updated documentation. -The [spec site](https://spec.openapis.org) is the source of truth for the OpenAPI specification as it contains all the citations and author credits (the markdown in this repository was previously the authoritative version until 2024). +If in doubt about a policy, please [ask on our Slack](https://communityinviter.com/apps/open-api/openapi) before opening a PR. -The OpenAPI project is almost entirely staffed by volunteers. -Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world. +### No changes to published specifications -### Active branches +No changes, ***no matter how trivial***, are ever made to the contents of published specifications. The only potential changes to those documents are updates to link URLs _if and only if_ the targeted document is moved by a 3rd party. Other changes to link URLs are not allowed. -The current active specification releases are: +### Authoritative source of truth -| Version | Branch | Notes | -| ------- | ------ | ----- | -| 3.1.2 | `v3.1-dev` | active patch release line | -| 3.2.0 | `v3.2-dev` | minor release in development | -| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | - - -## How to contribute - -We welcome new contributors to the project whether you have changes to suggest, problems to report, or some feedback for us. -Please jump to the most relevant section from the list below: - -- Ask a question or offer feedback: use a [discussion](#discussions) -- Suggest a change or report a problem: open an [issue](#issues) -- Contribute a change to the repository: open a [pull request](#pull-requests) -- Or just [get in touch](#get-in-touch) - -## Discussions - -We use [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for anything that doesn't (yet) have a specific action associated with it. -Most ideas start as discussions. - -Please do come and start a discussion to: - - - ask questions - - make suggestions - - give feedback - -Anyone can start a discussion and you're very welcome to do so! Write a message and pick a relevant discussion category. - -### Discussion management - -Participation in discussions and especially answering of questions is encouraged (and appreciated) by everyone. - -Discussions are closed when: - - - the question has been answered. - - no further action or conversation would be useful. - - there has been no engagement for a while, or a previously popular thread has been inactive for an extended period. - - activity is now taking place elsewhere, such as in an issue. - - the discussion is out of scope for the project. - -## Issues - -Issues are for planned tasks, problems to solve, or requests for (specific) changes. -Most issues should have a clear outcome; something will be fixed, improved or otherwise measurably different when the issue is complete. - -We use [discussions](#discussions) for ideas and early-stage suggestions. - -> [!NOTE] -> For larger or more extensive changes, we have a formal [proposal process](#propose-a-specification-change) to give more structure where it's needed. - -The best issues give a clear and concise explanation of the problem at hand, and ideally some examples of what the problem is. -Suggested solutions are also welcome, but it is very important that the issue outlines the problem that is being solved as well as the solution. -Some issues may be a backlog of a task that needs to be done; other issues might be automatically created as part of the project processes. - -### Issue management - -We have some issue automation to close inactive issues and create/pin/archive the weekly meeting issues. -More information is in the [Appendix: Issue automation](#appendix-issue-automation) section. - -Everyone is encouraged to open and comment on issues in the project. -If you want to tag/assign/close something and you don't have enough permissions, add a comment and someone will help. - -Issues are managed by the [Triage](#triage), [Maintainers](#maintainers) and [TSC](#tsc) teams. -They may move issues to other repositories within the project as needed. - -In order to keep the issues list manageable and realistic for a relatively small group of volunteers, issues are proactively closed when it's not clear that they can be completed. -Issues may be closed when: - -- they have been inactive for a long time -- they are out of scope or no further constructive action can be taken -- they are complete (yay!) -- they are unclear and more details are not forthcoming -- as a group, there is agreement that no further action will be taken - -When issues are closed, a comment is added about why. -Closing issues is a reversible action, and it is always acceptable to comment and explain (politely) why an issue should not have been closed. - -### Labels +The [spec site](https://spec.openapis.org) is the source of truth. -We make extensive use of labels. -The main categories are: +This changed in 2024, as the markdown files on `main` do not include certain credits and citations. -- [Housekeeping](https://github.com/OAI/OpenAPI-Specification/labels/Housekeeping) for meetings, project logistics, etc. -- [approved pr port](https://github.com/OAI/OpenAPI-Specification/labels/approved%20pr%20port) for pull requests that repeat a change from one version to another -- most other tags are used to group similar or related issues into topic areas; this list is ever-changing +## Development process -Labels related to [issue automation](#appendix-issue-automation) +As of October 2024 (post-OAS 3.0.4 and 3.1.1), the OAS is developed in the `src/oas.md` file on minor release `vX.Y-dev` branches that are derived from the baseline `dev` branch. -- [Needs attention](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20attention) automated tag when an issue is updated -- [Needs author feedback](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20author%20feedback) used to indicate that more information is needed from the issue creator -- [No recent activity](https://github.com/OAI/OpenAPI-Specification/labels/No%20recent%20activity) if no information is received, the issue is marked for closure (automatic after 30 days) +Schema changes are made on the same branch, but can be released independently. When making a specification change for a new minor or major release that has a schema impact, including the schema change in the PR is preferred. Patch releases cannot contain changes that _require_ a schema update. -### Milestones - -We use milestones in GitHub to plan what should be included in future releases. -Issues and pull requests should both be added to the earliest milestone we expect they will be released in. -Any changes that aren't ready in time for release should be moved to the next milestone or untagged. - -The milestones and items assigned to them are under constant review and subject to change. - -### Projects - -The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the specification development process. There are currently two active projects: - -* [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1) -* [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1) - -## Pull requests - -> [!NOTE] -> Since the 3.0.4 and 3.1.1 releases (October 2024), the OAS is developed in the `src/oas.md` file. -> Check the [Appendix: Branch Strategy](#appendix-branch-strategy) for more information about the updated branching strategy. - -Changes to the next version of the specification are welcome and can be proposed by anyone. - -For large changes that will need discussion, please use the [Proposal process](#propose-a-specification-change). -For other changes, we recommend [opening an issue](#issues) first, so that you can get some feedback and any extra input you need before spending a lot of time on something. - -Schema changes are made on the same branch, but can be released independently. -When making a specification change for a new minor or major release that has a schema impact, including the schema change in the PR is preferred. -Patch releases cannot contain changes that _require_ a schema update. - -### Use a fork - -All work **MUST be done on a fork** and be submitted as a pull request. - -### Target the earliest active `*-dev` branch - -Branch from and submit pull requests to the a branch from the _earliest relevant and [active](#active-branches)_ `vX.Y-dev` branch. -For example, if a change applies to both 3.1 and 3.2, the PR would go to the `v3.1-dev` branch, which will be merged up to `v3.2-dev` before the next 3.2 release. -All changes to the specification must conform to the [style guide](./style-guide.md). - -Both specification and schema changes follow this approach. - -For changes to repository files that affect all versions, use the `main` branch. -This might apply to, for example, Markdown files, automation, and scripts. - -For all pull requests, if they should not be merged yet for any reason (they depend on something else, you would like feedback from a specific reviewer), mark them as draft and they will not be merged while in that state. -Draft pull requests can still be reviewed while in draft state. - -### Preview specification HTML locally - -The markdown source files are converted to HTML before publishing. -To do this locally, please - -1. Install [Node.js](https://nodejs.org/) -2. Check out this repo, go to the repo root, and switch to a development branch -3. Execute `npm install` (once, repeat after merging upstream changes) -4. Execute `npm run build-src` after changing `src/oas.md` (this first executes `npm run validate-markdown`, which can also be run separately) -5. Open output file `deploy-preview/oas.html` with a browser and check your changes - -Please make sure the markdown validates and builds using the above steps before creating a pull request or marking a draft pull request as ready for review. - -## Reviewers - -> [!NOTE] -> See also the detailed team outlines in the [roles section](#roles). +### Branch roles -All pull requests must be reviewed and approved by one member of the TSC or Maintainers teams. -Reviews from other contributors are always welcome. +* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed. The `src` tree is ***not*** present on `main`. +* `dev` is the primary branch for working with the `src` tree, which is kept up-to-date with the most recent release on the most recent minor (X.Y) release line, and serves as the base for each new minor release line. Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed. +* `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions. All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document. +* `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0). It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links. -Additionally, all pull requests that change the specification file `src/oas.md` must be approved by two TSC members. +### Using forks -Reviews requesting changes should have their changes addressed regardless of how many other approvers there are. +All work **MUST be done on a fork**, using a branch from the _earliest relevant and [active](#active-branches)_ `vX.Y-dev` branch, and then submitted as a PR to that `vX.Y-dev` branch. +For example, if a change in November 2024 apples to both 3.1 and 3.2, the PR would go to the `v3.1-dev` branch, which will be merged up to `v3.2-dev` before the next 3.2 release. ## Publishing -### Specification Versions - -The specification versions are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`. -This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files). - -The HTML renderings of the specification versions are automatically generated from the `versions` directory on `main` by the [`respec` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml), which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org). - -### Schema Iterations - -The schema iterations are published independently from the specification releases [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas). -Schemas are updated in and directly published from the `vX.Y-dev` branches. - -As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is usually done by the `schema-publish` workflow which detects changes on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). The workflow can also be run manually if required. - -## Release Process and Scope - -This section relates to the 3.x versions only. - -### Minor Releases - -Our roadmap for 3.x releases is community-driven, meaning the specification is open for proposed additions by anyone (see [Propose a Specification Change](#propose-a-specification-change)), in addition to the issues already on the project backlog. - -Changes in minor releases (such as 3.2, 3.3) meet the following criteria: - -* Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version. - For example, new optional fields can be added. -* Drive quality-of-life improvements to support how OpenAPI is used by practitioners, so that OpenAPI evolves to continue to meet user needs. - For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification. -* Bring the future closer by making changes that are in line with future 3.x releases and the planned OpenAPI 4.x (Moonwalk) specification as the details of that become available. -* Make the specification document clearer or easier to understand. - -A minor release is due when there are some meaningful features (including one or a small number of headline features). - -### Patch Releases - -Patch releases reflect a constant quest for improving the active minor versions of OpenAPI. -Since we do not edit specification documents after publication, even the smallest change has to be in a new release. - -Changes in patch releases meet the following criteria: - -* Editorial changes such as spelling or formatting fixes, including link updates. -* Clarifications or additions that do not change the meaning of the specification. - -Patch releases are created as often as there are changes to the specification worth releasing. - -### Release Process - -A release requires a vote on the specification at a particular version and the associated release notes by TSC members within the voting period. -Major or minor release voting periods will be announced in the Slack channel and noted on the calendar at least 6 days in advance. -During this time, TSC members who have not yet voted must note their approval by leaving a comment on the GitHub pull request proposing the release; release notes should be included with the description. -TSC members are responsible for coordinating the information about the release to the outreach team as appropriate. - -* Patch-level releases require majority approval by TSC members. (Max voting period 3 days) - -* Minor: requires approval by 66% of TSC members. (Max voting period 7 days) - -* Major: requires approval by 66% of TSC members. (Max voting period 14 days) - -During the voting period, further changes should not be made to the specification being considered. - -Once the threshold of approvals is met, the release can be performed by any TSC member. - -## Propose a Specification Change - -As an organisation, we're open to changes, and these can be proposed by anyone. -The specification is very widely adopted, and there is an appropriately high bar for wide appeal and due scrutiny as a result. -We do not accept changes lightly (but we will consider any that we can). - -Small changes are welcome as pull requests. - -Bigger changes require a more formal process. - -1. Start a [discussion](https://github.com/OAI/OpenAPI-Specification/discussions) of type "Enhancements". - The discussion entry must include some use cases, your proposed solution and the alternatives you have considered. - If there is engagement and support for the proposal over time, then it can be considered as a candidate to move to the next stage. - -2. It really helps to see the proposed change in action. - Start using it as a `x-*` extension if that's appropriate, or try to bring other evidence of your proposed solution being adopted. - -3. If you are adding support for something from another specification (such as OAuth), please point to implementations of that - specification so that we can understand how, and to what degree, it is being used. - -4. If the suggested change has good support, you will be asked to create a formal proposal. - Use the [template in the proposals directory](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals), copy it to a new file, and complete it. - Once you the document is ready, open a pull request on the main branch. - -5. The proposal will be more closely reviewed and commented on or amended until it is either rejected or accepted. - At that point, the proposal is merged into the `main` branch and a pull request is opened to add the feature to the appropriate `dev` version of the specification. - -Questions are welcome on the process at any time. Use the discussions feature or find us in Slack. - -## Roles - -The OpenAPI project has some key roles that are played by multiple people. - -### TSC - -The Technical Steering Committee are listed in the [MAINTAINERS file](./MAINTAINERS.md). -They are the maintainers of the OpenAPI Specification itself and every other aspect of the project operation and direction. -TSC members can review changes to all parts of the repository and make decisions about the project. - -### Maintainers - -The maintainers have write access to the repository and play a key role in the project. -They review pull requests to non-specification parts of the repository, and take on other strategic tasks around project planning and maintenance. - -### Triage +The specification and schemas are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`. The HTML versions of the OAS are automatically generated from the `versions` directory on `main`. This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files). -The triage team are active OpenAPI members who help with discussion and issue management. -They respond to new issues and discussions, direct people to our existing resources or raise conversations to a wider audience. -The triage team keeps an eye on the backlog and closes issues and discussions that are no longer active or needed. +The publishing process for schemas is still under discussion (see issues [#3715](https://github.com/OAI/OpenAPI-Specification/issues/3715) and [#3716](https://github.com/OAI/OpenAPI-Specification/issues/3716)), with the current proposal being to release them directly from the `vX.Y-dev` branch without merging to `main`, as the schemas in source control have placeholder identifiers and are not intended to be used as-is. -## Get in touch - -To get in touch with other people on the project, ask questions, or anything else: - -- Find us [on the OpenAPI Slack](https://communityinviter.com/apps/open-api/openapi). -- Start a [GitHub Discussion](https://github.com/OAI/OpenAPI-Specification/discussions/). -- Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHousekeeping). - -## Appendix: Branch strategy +### Historical branch strategy For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and earlier, see the comments in [issue #3677](https://github.com/OAI/OpenAPI-Specification/issues/3677). -### Branch roles - -* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed. The `src` tree is ***not*** present on `main`. -* `dev` is the primary branch for working with the `src` tree, which is kept up-to-date with the most recent release on the most recent minor (X.Y) release line, and serves as the base for each new minor release line. Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed. - Changes on `main` are automatically included in a pull request to `dev` (see the (section on [branch sync](#branch-sync-automation)). -* `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions. All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document. -* `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0). It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links. - ### Branching and merging (3.1.2, 3.2.0, and later) Upon release: * Pre-release steps: - * The most recent _published_ patch release from the previous line is merged up to `vX.Y-dev`, if relevant + * The most recent _published_ patch release from the previoius line is merged up to `vX.Y-dev`, if relevant * If doing simultaneous releases on multiple lines, do them from the oldest to newest line * If the release is the most recent on the current line, merge `vX.Y-dev` to `dev` * For example, if releasing 3.1.3 and 3.2.0: @@ -437,18 +163,155 @@ gitGraph TB: commit id:"3.3 work" ``` -### Branch sync automation +#### Active branches + +The first PR for a change should be against the oldest release line to which it applies. Changes can then be forward-ported as appropriate. + +The specification under development is `src/oas.md`, which _only_ exists on development branches, not on `main`. + +The current (20 October 2024) active specification releases are: + +| Version | Branch | Notes | +| ------- | ------ | ----- | +| 3.1.2 | `v3.1-dev` | active patch release line | +| 3.2.0 | `v3.2-dev` | minor release in development | +| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | + +## Style Guide + +Contributions to this repository should follow the style guide as described in this section. + +### Markdown + +Markdown files in this project should follow the style enforced by the [markdownlint tool](https://www.npmjs.com/package/markdownlint), +as configured by the `.markdownlint.yaml` file in the root of the project. +The `markdownlint` tool can also fix formatting, which can save time with tables in particular. + +The following additional rules should be followed but currently are not enforced by tooling: + +1. The first mention of a normative reference or an OAS-defined Object in a (sub)*section is a link, additional mentions are not. +2. OAS-defined Objects such as Schema Objects are written in this style, and are not monospaced. +3. Use "example" instead of "sample" - this spec is not about statistics. +4. Use "OpenAPI Object" instead of "root". +5. Fixed fields are monospaced. +6. Field values are monospaced in JSON notation: `true`, `false`, `null`, `"header"` (with double-quotes around string values). +7. A combination of fixed field name with example value uses JS notation: `in: "header"`, combining rules 5 and 6. +8. An exception to 5-7 is colloquial use, for example "values of type `array` or `object`" - "type" is not monospaced, so the monospaced values aren't enclosed in double quotes. +9. Use Oxford commas, avoid Shatner commas. +10. Use `` for link anchors. The `` format has been deprecated. +11. Headings use [title case](https://en.wikipedia.org/wiki/Title_case) and are followed by a blank line. + +Plus some suggestions, rather than rules: + +* Use one sentence per line in paragraphs and bullet points, to make diffs and edits easier to compare and understand. + A blank line is needed to cause a paragraph break in Markdown. +* In examples, use realistic values rather than foo/bar. + +### Use of "keyword", "field", "property", and "attribute" + +* JSON Schema keywords -> "keyword" +* OpenAPI fixed fields -> "field" +* property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property" +* "attribute" is only used in the XML context and means "XML attribute" + +### Field Names and Values in YAML comments + +Field names and keywords should be in backticks. +Values like "Dog" should be double quoted. + +## Release Process and Scope + +This section relates to the 3.x versions only. + +### Minor Releases + +Our roadmap for 3.x releases is community-driven, meaning the specification is open for proposed additions by anyone (see [Proposals for Specification Changes](#proposals-for-specification-changes)), in addition to the issues already on the project backlog. + +Changes in minor releases (such as 3.2, 3.3) meet the following criteria: + +* Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version. + For example, new optional fields can be added. +* Drive quality-of-life improvements to support how OpenAPI is used by practitioners, so that OpenAPI evolves to continue to meet user needs. + For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification. +* Bring the future closer by making changes that are in line with future 3.x releases and the planned OpenAPI 4.x (Moonwalk) specification as the details of that become available. +* Make the specification document clearer or easier to understand. + +A minor release is due when there are some meaningful features (including one or a small number of headline features). + +### Patch Releases + +Patch releases reflect a constant quest for improving the active minor versions of OpenAPI. +Since we do not edit specification documents after publication, even the smallest change has to be in a new release. + +Changes in patch releases meet the following criteria: + +* Editorial changes such as spelling or formatting fixes, including link updates. +* Clarifications or additions that do not change the meaning of the specification. + +Patch releases are created as often as there are changes to the specification worth releasing. + +## Branching and Versioning + +* Issue #3677: [Define and document branch strategy for the spec, both development and publishing](https://github.com/OAI/OpenAPI-Specification/issues/3677) + +## Proposals for Specification Changes + +As an organisation, we're open to changes, and these can be proposed by anyone. +The specification is very widely adopted, and there is an appropriately high bar for wide appeal and due scrutiny as a result. +We do not accept changes lightly (but we will consider any that we can). + +Small changes are welcome as pull requests. + +Bigger changes require a more formal process. + +1. Start a [discussion](https://github.com/OAI/OpenAPI-Specification/discussions) of type "Enhancements". + The discussion entry must include some use cases, your proposed solution and the alternatives you have considered. + If there is engagement and support for the proposal over time, then it can be considered as a candidate to move to the next stage. + +2. It really helps to see the proposed change in action. + Start using it as a `x-*` extension if that's appropriate, or try to bring other evidence of your proposed solution being adopted. + +3. If you are adding support for something from another specification (such as OAuth), please point to implementations of that + specification so that we can understand how, and to what degree, it is being used. + +4. If the suggested change has good support, you will be asked to create a formal proposal. + Use the [template in the proposals directory](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals), copy it to a new file, and complete it. + Once you the document is ready, open a pull request on the main branch. + +5. The proposal will be more closely reviewed and commented on or amended until it is either rejected or accepted. + At that point, the proposal is merged into the `main` branch and a pull request is opened to add the feature to the appropriate `dev` version of the specification. -To keep changes in sync, we have some GitHub actions that open pull requests to take changes from `main` onto the `dev` branch, and from `dev` to each active version branch. +Questions are welcome on the process at any time. Use the discussions feature or find us in Slack. + +## Working in GitHub -- `sync-main-to-dev` opens a pull request with all the changes from the `main` branch that aren't yet included on `dev`. -- `sync-dev-to-vX.Y-dev` opens pull requests with all the changes from `dev` that aren't yet included on the corresponding `vX.Y-dev` branch. +* Issue #3847: [Document milestone usage in DEVELOPMENT.md](https://github.com/OAI/OpenAPI-Specification/issues/3847) +* Issue #3848: [Define and add new process labels and document general label usage in DEVELOPMENT.md](https://github.com/OAI/OpenAPI-Specification/issues/3848) -These need a single approval from either maintainers or TSC and can be merged. -The aim is to bring build script and repository documentation changes to the other branches. -Published versions of the specifications and schemas will also move across branches with this approach. +### Roles and Permissions -## Appendix: Issue Automation +* Issue #3582: [TOB info needs to be updated](https://github.com/OAI/OpenAPI-Specification/issues/3482) +* Issue #3523: [Define triage role criteria and process](https://github.com/OAI/OpenAPI-Specification/issues/3523) +* Issue #3524: [Define the maintainer role criteria and process](https://github.com/OAI/OpenAPI-Specification/issues/3524) + +### Projects + +The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the specification development process. There are currently two active projects: + +* [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1) +* [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1) + +### Discussions + +We are beginning (as of mid-2024) to use GitHub [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for open-ended topics such as major enhancements. + +* Issue #3518: [Define criteria for filing/closing issues vs discussions](https://github.com/OAI/OpenAPI-Specification/issues/3518) + +### Issues + +As of mid-2024, we prefer to use issues for topics that have a clear associated action. However, many existing issues are more open-ended, as they predate GitHub's discussions features. + +* Issue #3518: [Define criteria for filing/closing issues vs discussions](https://github.com/OAI/OpenAPI-Specification/issues/3518) ### Automated closure of issues Process @@ -464,4 +327,14 @@ This process makes use of the following labels: An issue is opened every week, 7 days in advance, for the Technical Developer Community (TDC), it provides the information to connect the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping". -Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. \ No newline at end of file +Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. + +## Pull Requests + +* Issue #3581: [Who and how many people need to sign-off on a PR, exactly?](https://github.com/OAI/OpenAPI-Specification/issues/3581) +* Issue #3802: [Define a policy using draft PRs when waiting on specific approvals](https://github.com/OAI/OpenAPI-Specification/issues/3802) + +## Updating the Registries + +* Issue #3598: [Minimum criteria for Namespace Registry](https://github.com/OAI/OpenAPI-Specification/issues/3598) +* Issue #3899: [Expert review criteria for registries (How exactly does x-twitter work?)](https://github.com/OAI/OpenAPI-Specification/issues/3899) From c609a46ebfb9d821e9ee0cf3679424b20e2e5135 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Mar 2025 23:13:28 +0100 Subject: [PATCH 4/7] Revert "Update CONTRIBUTING.md" This reverts commit 97e7b3d6fead90242a599e09d8ffcf36acead4f7. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b48f0096bc..2c2db67e7b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,7 +216,7 @@ Plus some suggestions, rather than rules: ### Field Names and Values in YAML comments -Field names and keywords should be in backticks. +Field names and keys should be in backticks. Values like "Dog" should be double quoted. ## Release Process and Scope From 67ac64d783b75a5e5b625aad4fbc7bf0cac1b220 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Mar 2025 23:13:32 +0100 Subject: [PATCH 5/7] Revert "Update CONTRIBUTING.md" This reverts commit c2c9aaf9e110485ac3e1942eb75bdb063e2bb67f. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c2db67e7b..3d217ec28c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,8 +216,8 @@ Plus some suggestions, rather than rules: ### Field Names and Values in YAML comments -Field names and keys should be in backticks. -Values like "Dog" should be double quoted. +Field names and keys should be in backticks for consistency. +Values like "Dog" should be double quoted as they are a value rather than a keyword. ## Release Process and Scope From fb2bc8ed8a5f6ba771aeedc8e77ac7fa16547b66 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Mar 2025 23:13:40 +0100 Subject: [PATCH 6/7] Revert "Update CONTRIBUTING.md" This reverts commit 5d505db64de684c163e47ade8f8347c9c320d5d9. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d217ec28c..0a7542e912 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,7 +216,7 @@ Plus some suggestions, rather than rules: ### Field Names and Values in YAML comments -Field names and keys should be in backticks for consistency. +Field names and entries such as content types should be in backticks, they would be fixed-width fonts if the markdown was rendered (which the comments are not). Values like "Dog" should be double quoted as they are a value rather than a keyword. ## Release Process and Scope From 86f3f67c2cc74748d741335977926c1001894a72 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Mar 2025 23:13:45 +0100 Subject: [PATCH 7/7] Revert "Update CONTRIBUTING.md" This reverts commit 17ab8d6cb4e947c02dd61070aedd532568740e0b. --- CONTRIBUTING.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a7542e912..7cc369eb4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -214,11 +214,6 @@ Plus some suggestions, rather than rules: * property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property" * "attribute" is only used in the XML context and means "XML attribute" -### Field Names and Values in YAML comments - -Field names and entries such as content types should be in backticks, they would be fixed-width fonts if the markdown was rendered (which the comments are not). -Values like "Dog" should be double quoted as they are a value rather than a keyword. - ## Release Process and Scope This section relates to the 3.x versions only.