From 2705cfdf7d8e99d9bb100d8f951a7efee36b0e87 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 31 Jul 2024 15:13:26 -0700 Subject: [PATCH 1/4] Begin DEVELOPMENT.md -> CONTRIBUTING.md Create a new CONTRIBUTING.md and link it and DEVELOPMENT.md to each other. Move the recent sections over to CONTRIBUTING.md, and outline sections to organize the various topics that have issues tracking them. --- CONTRIBUTING.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++ DEVELOPMENT.md | 66 +++--------------------- 2 files changed, 140 insertions(+), 58 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..e647c24cfe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,132 @@ +# Contributing to the OpenAPI Specification + +***Work in progress!*** + +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. + +## Essential Policies + +This section serves as a quick guide while we work on the full updated documentation. + +If in doubt about a policy, please [ask on our Slack](https://communityinviter.com/apps/open-api/openapi) before opening a PR. + +### No changes to published specifications + +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. + +### Current branches and documents open to change + +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 current (31 July 2024) active releases are: + +| Version | Branch | File | Notes | +| ------- | ------ | ---- | ----- | +| 3.0.4 | `v3.0.4-dev` | `versions/3.0.4.md` | Soon to be published | +| 3.1.1 | `v3.1.1-dev` | `versions/3.1.1.md` | Soon to be published | +| 3.2.0 | `v3.2.0-dev` | `versions/3.2.0.md` | Planned for late 2024 | +| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | TBD, some proposals to be backported and published in 3.2.0 | + +### Changing the schemas + +Schemas are only changed _after_ the specification is changed. Changes are made on the `main` branch, and should be made to the YAML version _only_. The JSON version will be generated automatically. + +## Authoritative source of truth + +* Issue #3576: [What is our authoritative spec URL and how do people find it?](https://github.com/OAI/OpenAPI-Specification/issues/3576) + +## Release Process and Scope + +* Issue #3528: [3.x.y patch release approach](https://github.com/OAI/OpenAPI-Specification/issues/3528) +* Issue #3529: [3.x minor release approach](https://github.com/OAI/OpenAPI-Specification/issues/3528) +* Issue #3715: [Define and document our schema publishing process](https://github.com/OAI/OpenAPI-Specification/issues/3715) +* Issue #3785: [Style guide / release checklist for the specification](https://github.com/OAI/OpenAPI-Specification/issues/3785) + +## 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. + +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 to the `main` branch and a final pull request is opened to add the feature to the appropriate version of the specification. + +Questions are welcome on the process and at any time. Use the discussions feature or find us in Slack. + +## Working in GitHub + +* 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) + +### Roles and Permissions + +* 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/Arazzo-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 + +In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive. + +This process makes use of the following labels: + +* Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow. +* No recent activity: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow. +* Needs attention: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow. + +### Automated TDC agenda issues Process + +An issue is opened every week, 7 days in advance, for the Technical Direction Committee (TDC), it provides the information to connect the 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) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 5a8598328d..dd8eb26602 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,31 +1,14 @@ +# CHANGES IN PROGRESS!! + +Please see [CONTRIBUTING.md](CONTRIBUTING.md) for up-to-date guidelines. While we continue to [define and document our new processes](https://github.com/orgs/OAI/projects/5), we will keep this document as much of its contents are still relevant. However, if in doubt about a policy, please [ask on our Slack](https://communityinviter.com/apps/open-api/openapi). + ## Development Guidelines This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The OpenAPI Technical Steering Committee (TSC) will initially follow these processes when merging changes from external contributors or from the TSC itself. This guideline document will be adjusted as practicality dictates. ### Essential Policies -If in doubt about a policy, please [ask on our Slack](https://communityinviter.com/apps/open-api/openapi) before opening a PR. - -#### No changes to published specifications - -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. - -#### Current branches and documents open to change - -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 current (February 2024) active releases are: - -| Version | Branch | File | -| ------- | ------ | ---- | -| 3.0.4 | `v3.0.4-dev` | `versions/3.0.4.md` | -| 3.1.1 | `v3.1.1-dev` | `versions/3.1.1.md` | -| 3.2.0 | `v3.2.0-dev` | `versions/3.2.0.md` | -| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | - -#### Changing the schemas - -Schemas are only changed _after_ the specification is changed. Changes are made on the `main` branch, and should be made to the YAML version _only_. The JSON version will be generated automatically. +See [CONTRIBUTING.md](CONTRIBUTING.md) ## OAI Specification Driving factors @@ -59,32 +42,7 @@ Spec changes should be approved by a majority of the committers. Approval can be ### 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. - -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 to the `main` branch and a final pull request is opened to add the feature to the appropriate version of the specification. - -Questions are welcome on the process and at any time. Use the discussions feature or find us in Slack. +See [CONTRIBUTING.md](CONTRIBUTING.md) ## Tracking Process @@ -134,19 +92,11 @@ The process should be as transparent as possible. Sometimes there will be discus ## Automated closure of issues Process -In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive. - -This process makes use of the following labels: - -* Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow. -* No recent activity: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow. -* Needs attention: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow. +See [CONTRIBUTING.md](CONTRIBUTING.md) ## Automated TDC agenda issues Process -An issue is opened every week, 7 days in advance, for the Technical Direction Committee (TDC), it provides the information to connect the 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. +See [CONTRIBUTING.md](CONTRIBUTING.md) ## Participation From b7c132bc06f1cb0c9742811ffc28c857498d7d5c Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 1 Aug 2024 07:28:19 -0700 Subject: [PATCH 2/4] Remove duplicated word. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e647c24cfe..2a7636de0b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,7 +117,7 @@ This process makes use of the following labels: ### Automated TDC agenda issues Process -An issue is opened every week, 7 days in advance, for the Technical Direction Committee (TDC), it provides the information to connect the 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". +An issue is opened every week, 7 days in advance, for the Technical Direction Committee (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. From 34a81b791b1729044b5111540bf96e0e2afd4f25 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 1 Aug 2024 09:58:21 -0700 Subject: [PATCH 3/4] Review feedback --- CONTRIBUTING.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a7636de0b..9b4baee13f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to the OpenAPI Specification -***Work in progress!*** +***Work in progress!** Each section links to issues that are relevant to fill out the rest of this document.* 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. @@ -38,7 +38,7 @@ Schemas are only changed _after_ the specification is changed. Changes are made ## Release Process and Scope * Issue #3528: [3.x.y patch release approach](https://github.com/OAI/OpenAPI-Specification/issues/3528) -* Issue #3529: [3.x minor release approach](https://github.com/OAI/OpenAPI-Specification/issues/3528) +* Issue #3529: [3.x minor release approach](https://github.com/OAI/OpenAPI-Specification/issues/3529) * Issue #3715: [Define and document our schema publishing process](https://github.com/OAI/OpenAPI-Specification/issues/3715) * Issue #3785: [Style guide / release checklist for the specification](https://github.com/OAI/OpenAPI-Specification/issues/3785) @@ -68,12 +68,12 @@ Bigger changes require a more formal process. 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. + 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 to the `main` branch and a final pull request is opened to add the feature to the appropriate version of the specification. + 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 and at any time. Use the discussions feature or find us in Slack. +Questions are welcome on the process at any time. Use the discussions feature or find us in Slack. ## Working in GitHub @@ -95,7 +95,7 @@ The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the spec ### Discussions -We are beginning (as of mid-2024) to use GitHub [discussions](https://github.com/OAI/Arazzo-Specification/discussions?discussions_q=is%3Aopen) for open-ended topics such as major enhancements. +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) @@ -111,13 +111,13 @@ In an effort to keep the list of issues up to date and easier to navigate throug This process makes use of the following labels: -* Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow. -* No recent activity: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow. -* Needs attention: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow. +* `Needs author feedback`: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow. +* `No recent activity`: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow. +* `Needs attention`: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow. ### Automated TDC agenda issues Process -An issue is opened every week, 7 days in advance, for the Technical Direction Committee (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". +An issue is opened every week, 7 days in advance, for the Technical Developer Committee (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. From 8b6590b3f2086009df23d5ed462d505c021b9e37 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 2 Aug 2024 16:20:17 +0200 Subject: [PATCH 4/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b4baee13f..253d211d55 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,7 +117,7 @@ This process makes use of the following labels: ### Automated TDC agenda issues Process -An issue is opened every week, 7 days in advance, for the Technical Developer Committee (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". +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.