From dae55231b744a4bd754f299859205c6a00c6cd91 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 5 Dec 2024 20:48:15 +0000 Subject: [PATCH 1/8] Start refactoring contributor information: issues, discusssions, roles --- CONTRIBUTING.md | 394 ++++++++++++++++++++++++++++++------------------ 1 file changed, 248 insertions(+), 146 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7cc369eb4e..74cd1f6abe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,100 @@ -# 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. +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 do this because they believe in it. -### No changes to published specifications +## How to contribute -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. +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: -### Authoritative source of truth +- 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) -The [spec site](https://spec.openapis.org) is the source of truth. +## Discussions -This changed in 2024, as the markdown files on `main` do not include certain credits and citations. +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), [Maintainer](#maintainer) 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. ## Development process -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. +> [!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 [Branches](#branches) section 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. @@ -44,125 +116,6 @@ The specification and schemas are published to the [spec site](https://spec.open 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. -### 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). - -### 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 - * 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: - * release 3.1.3 first, including merging `v3.1-dev` to `dev` as 3.1 is current at that moment - * release 3.2.0 second, also merging `v3.2-dev` to `dev` as 3.2 becomes current at that point - * any subsequent 3.1.4 would **_not_** trigger a merge of `v3.1-dev` to `dev`, as 3.1 would no longer be current -* Release branching and merging: - * branch `vX.Y.Z-rel` from `vX.Y-dev` (same commit that was merged to `dev` if relevant) - * After renaming `src/oas.md` to `versions/X.Y.Z.md`, merge `vX.Y.Z-rel` to `main` -* Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main` -* Post-release steps: - * If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `dev`, from the commit where `vX.Y-dev` was merged to `dev` - -_Release lines are grouped by color, although the colors of `dev` and `main` are not significant as these diagrams are limited to only 8 colors._ - -```mermaid ---- -config: - themeVariables: - git0: "#5588bb" - git1: "#cc8899" - git2: "#eedd88" - git3: "#ccbb66" - git4: "#aa9944" - git5: "#887722" - git6: "#99ccff" - git7: "#77aadd" - gitBranchLabel1: "#000000" - gitBranchLabel2: "#000000" - gitBranchLabel3: "#000000" - gitBranchLabel4: "#000000" - gitBranchLabel5: "#ffffff" - gitBranchLabel6: "#000000" - gitBranchLabel7: "#000000" ---- -gitGraph TB: - commit id:"merge 3.1.1.md to main" tag:"3.1.1" - branch dev order:1 - commit id:"rename 3.1.1.md to src/oas.md" - branch v3.1-dev order:2 - commit id:"update version in src/oas.md to 3.1.2" - checkout dev - branch v3.2-dev order:6 - commit id:"update version in src/oas.md to 3.2.0" - commit id:"some 3.2.0 work" - checkout v3.1-dev - commit id:"a 3.1.x fix" - checkout v3.2-dev - merge v3.1-dev id:"merge 3.1.2 fixes" - checkout v3.1-dev - branch v3.1.2-rel order:3 - commit id:"rename src/oas.md to versions/3.1.2.md" - checkout dev - merge v3.1-dev id:"update dev with active line patch release" - checkout main - merge v3.1.2-rel tag:"3.1.2" - checkout v3.2-dev - commit id:"more 3.2.0 work" - checkout v3.1-dev - commit id:"update version in src/oas.md to 3.1.3" - commit id:"another 3.1.x fix" - checkout v3.2-dev - commit id:"still more 3.2.0 work" - merge v3.1-dev id:"merge 3.1.3 fixes before releasing" - checkout dev - merge v3.1-dev id:"update dev with last pre-minor release patch release" - merge v3.2-dev id:"update dev with minor release" - checkout v3.1-dev - branch v3.1.3-rel order:4 - commit id:"rename src/oas.md to versions/3.1.3.md" - checkout v3.2-dev - branch v3.2.0-rel order:7 - commit id:"rename src/oas.md to versions/3.2.0.md" - checkout main - merge v3.1.3-rel tag:"3.1.3" - merge v3.2.0-rel tag:"3.2.0" - checkout dev - branch v3.3-dev order:9 - checkout v3.1-dev - commit id:"update version in src/oas.md to 3.1.4" - checkout v3.2-dev - commit id:"update version in src/oas.md to 3.2.1" - checkout v3.3-dev - commit id:"update version in src/oas.md to 3.3.0" - - checkout v3.1-dev - commit id:"a 3.1.4 fix" - checkout v3.2-dev - commit id:"a 3.2.1 fix" - merge v3.1-dev id:"merge 3.1.4 fixes before releasing" - checkout v3.3-dev - merge v3.2-dev id:"merge 3.1.4 / 3.2.1 fixes" - checkout dev - merge v3.2-dev id:"merge patch from active release line" - checkout v3.1-dev - branch v3.1.4-rel order:5 - commit id:"rename src/oas.md to versions/3.1.4.md" - checkout v3.2-dev - branch v3.2.1-rel order:8 - commit id:"rename src/oas.md to versions/3.2.1.md" - checkout main - merge v3.1.4-rel tag:"3.1.4" - merge v3.2.1-rel tag:"3.2.1" - checkout v3.2-dev - commit id:"update version in src/oas.md to 3.2.2" - checkout v3.3-dev - 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. @@ -249,7 +202,7 @@ Patch releases are created as often as there are changes to the specification wo * 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 +## 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. @@ -296,17 +249,175 @@ The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the spec * [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1) * [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1) -### Discussions +### Issues -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. +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) -### 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. +## Pull Requests -* Issue #3518: [Define criteria for filing/closing issues vs discussions](https://github.com/OAI/OpenAPI-Specification/issues/3518) +* 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) + +## 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 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. + +## 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: 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). + +### 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 + * 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: + * release 3.1.3 first, including merging `v3.1-dev` to `dev` as 3.1 is current at that moment + * release 3.2.0 second, also merging `v3.2-dev` to `dev` as 3.2 becomes current at that point + * any subsequent 3.1.4 would **_not_** trigger a merge of `v3.1-dev` to `dev`, as 3.1 would no longer be current +* Release branching and merging: + * branch `vX.Y.Z-rel` from `vX.Y-dev` (same commit that was merged to `dev` if relevant) + * After renaming `src/oas.md` to `versions/X.Y.Z.md`, merge `vX.Y.Z-rel` to `main` +* Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main` +* Post-release steps: + * If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `dev`, from the commit where `vX.Y-dev` was merged to `dev` + +_Release lines are grouped by color, although the colors of `dev` and `main` are not significant as these diagrams are limited to only 8 colors._ + +```mermaid +--- +config: + themeVariables: + git0: "#5588bb" + git1: "#cc8899" + git2: "#eedd88" + git3: "#ccbb66" + git4: "#aa9944" + git5: "#887722" + git6: "#99ccff" + git7: "#77aadd" + gitBranchLabel1: "#000000" + gitBranchLabel2: "#000000" + gitBranchLabel3: "#000000" + gitBranchLabel4: "#000000" + gitBranchLabel5: "#ffffff" + gitBranchLabel6: "#000000" + gitBranchLabel7: "#000000" +--- +gitGraph TB: + commit id:"merge 3.1.1.md to main" tag:"3.1.1" + branch dev order:1 + commit id:"rename 3.1.1.md to src/oas.md" + branch v3.1-dev order:2 + commit id:"update version in src/oas.md to 3.1.2" + checkout dev + branch v3.2-dev order:6 + commit id:"update version in src/oas.md to 3.2.0" + commit id:"some 3.2.0 work" + checkout v3.1-dev + commit id:"a 3.1.x fix" + checkout v3.2-dev + merge v3.1-dev id:"merge 3.1.2 fixes" + checkout v3.1-dev + branch v3.1.2-rel order:3 + commit id:"rename src/oas.md to versions/3.1.2.md" + checkout dev + merge v3.1-dev id:"update dev with active line patch release" + checkout main + merge v3.1.2-rel tag:"3.1.2" + checkout v3.2-dev + commit id:"more 3.2.0 work" + checkout v3.1-dev + commit id:"update version in src/oas.md to 3.1.3" + commit id:"another 3.1.x fix" + checkout v3.2-dev + commit id:"still more 3.2.0 work" + merge v3.1-dev id:"merge 3.1.3 fixes before releasing" + checkout dev + merge v3.1-dev id:"update dev with last pre-minor release patch release" + merge v3.2-dev id:"update dev with minor release" + checkout v3.1-dev + branch v3.1.3-rel order:4 + commit id:"rename src/oas.md to versions/3.1.3.md" + checkout v3.2-dev + branch v3.2.0-rel order:7 + commit id:"rename src/oas.md to versions/3.2.0.md" + checkout main + merge v3.1.3-rel tag:"3.1.3" + merge v3.2.0-rel tag:"3.2.0" + checkout dev + branch v3.3-dev order:9 + checkout v3.1-dev + commit id:"update version in src/oas.md to 3.1.4" + checkout v3.2-dev + commit id:"update version in src/oas.md to 3.2.1" + checkout v3.3-dev + commit id:"update version in src/oas.md to 3.3.0" + + checkout v3.1-dev + commit id:"a 3.1.4 fix" + checkout v3.2-dev + commit id:"a 3.2.1 fix" + merge v3.1-dev id:"merge 3.1.4 fixes before releasing" + checkout v3.3-dev + merge v3.2-dev id:"merge 3.1.4 / 3.2.1 fixes" + checkout dev + merge v3.2-dev id:"merge patch from active release line" + checkout v3.1-dev + branch v3.1.4-rel order:5 + commit id:"rename src/oas.md to versions/3.1.4.md" + checkout v3.2-dev + branch v3.2.1-rel order:8 + commit id:"rename src/oas.md to versions/3.2.1.md" + checkout main + merge v3.1.4-rel tag:"3.1.4" + merge v3.2.1-rel tag:"3.2.1" + checkout v3.2-dev + commit id:"update version in src/oas.md to 3.2.2" + checkout v3.3-dev + commit id:"3.3 work" +``` + +## Appendix: Issue Automation ### Automated closure of issues Process @@ -324,12 +435,3 @@ An issue is opened every week, 7 days in advance, for the Technical Developer Co 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 9b395fe40dc333f100732c9253fa05e2e32fe950 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 9 Dec 2024 15:54:31 +0000 Subject: [PATCH 2/8] Fill in more missing sections and try to keep the ordering sane --- CONTRIBUTING.md | 190 ++++++++++++++++++++++++------------------------ 1 file changed, 94 insertions(+), 96 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74cd1f6abe..dccdb21e4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,10 +8,23 @@ All participants are expected to read and follow this code. 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. +The specification is in the file `spec/oas.md`. + 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). The OpenAPI project is almost entirely staffed by volunteers. -Please be patient with the people in this project, who all have other jobs and do this because they believe in it. +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. + +### Active branches + +The current 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) | + ## How to contribute @@ -85,87 +98,90 @@ Issues may be closed when: 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. -## Development process +### Labels -> [!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 [Branches](#branches) section for more information about the updated branching strategy. +We make extensive use of labels. +The main categories are: -Changes to the next version of the specification are welcome and can be proposed by anyone. +- [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 pr port) 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 -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. +Labels related to [issue automation](#appendix-issue-automation) -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. +- [Needs attention](https://github.com/OAI/OpenAPI-Specification/labels/Needs attention) automated tag when an issue is updated +- [Needs author feedback](https://github.com/OAI/OpenAPI-Specification/labels/Needs author feedback) used to indicate that more information is needed from the issue creator +- [No recent activity](https://github.com/OAI/OpenAPI-Specification/labels/No recent activity) if no information is received, the issue is marked for closure (automatic after 30 days) -### Branch roles +### Milestones -* `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 milestones in GitHub to plan what should be included in future releases. +Issues and pull requests should both be added to the 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. -### Using forks +The milestones and items assigned to them are under constant review and subject to change. -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. +### Projects -## Publishing +The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the specification development process. There are currently two active projects: -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). +* [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1) +* [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1) -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. +## Pull requests -#### Active branches +> [!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 [Branches](#branches) section for more information about the updated branching strategy. -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. +Changes to the next version of the specification are welcome and can be proposed by anyone. -The specification under development is `src/oas.md`, which _only_ exists on development branches, not on `main`. +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. -The current (20 October 2024) active specification releases are: +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. -| 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) | +### Use a fork -## Style Guide +All work **MUST be done on a fork** and be submitted as a pull request. -Contributions to this repository should follow the style guide as described in this section. +### Target the earliest active `*-dev` branch -### Markdown +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). -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. +Both specification and schema changes follow this approach. -The following additional rules should be followed but currently are not enforced by tooling: +For changes to repository files that affect all versions, use the `main` branch. +This might apply to, for example, Markdown files, automation, and scripts. -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. +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. -Plus some suggestions, rather than rules: +## Reviewers + +> ![NOTE] +> See also the detailed team outlines in the [roles section](#roles). -* 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. +All pull requests must be reviewed and approved by one member of the TSC or Maintainer teams. +Reviews from other contributors are always welcome. -### Use of "keyword", "field", "property", and "attribute" +Additionally, all pull requests that change the specification file `spec/oas.md` must be approved by 2 TSC members. -* 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" +Reviews requesting changes should have their changes addressed regardless of how many other approvers there are. + +## Publishing + +The specification 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 schemas are published [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas). +As part of the publishing process, the `WORK-IN-PROGRESS` placeholders are replaced with dates as appropriate. +Schemas are published/updated independently from the specification releases. ## Release Process and Scope @@ -198,9 +214,22 @@ Changes in patch releases meet the following criteria: Patch releases are created as often as there are changes to the specification worth releasing. -## Branching and Versioning +### 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. -* Issue #3677: [Define and document branch strategy for the spec, both development and publishing](https://github.com/OAI/OpenAPI-Specification/issues/3677) +* 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 @@ -231,41 +260,6 @@ Bigger changes require a more formal process. Questions are welcome on the process 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) - -### 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) - - -## 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) - ## Roles The OpenAPI project has some key roles that are played by multiple people. @@ -295,13 +289,17 @@ To get in touch with other people on the project, ask questions, or anything els - 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: 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. +* `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: From 31af874a0000f69260930c6cbdca0dafe6ce898f Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 9 Dec 2024 15:54:56 +0000 Subject: [PATCH 3/8] Remove the now-outdated DEVELOPMENT file, it is replaced by CONTRIBUTING --- DEVELOPMENT.md | 115 ------------------------------------------------- 1 file changed, 115 deletions(-) delete mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index 6685c21bfb..0000000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,115 +0,0 @@ -# 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 - -See [CONTRIBUTING.md](CONTRIBUTING.md) - -## OAI Specification Driving factors - -The OpenAPI Specification should be use-case driven. We can specify support for hypothetical use cases as we see fit, but specifications should be backed by realistic scenarios. - -## Specification Change Criteria - -The specification *will evolve over time*. Changes may be made when any of the following criteria are met: - -* Clarity. The current "way" something is done doesn't make sense, is complicated, or not clear. - -* Consistency. A portion of the specification is not consistent with the rest, or with the industry standard terminology. - -* Necessary functionality. We are missing functionality because of a certain design of the specification. - -* Forward-looking designs. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. - -* Impact. A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the *common* and *important* use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. - -## Specification Change Process - -For each change in the specification we should *always* consider the following: - -* Migration. Is this a construct that has a path from the [existing specification](https://github.com/OAI/OpenAPI-Specification/releases)? If so, how complicated is it to migrate to the proposed change? - -* Tooling. Strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. - -* Visualization. Can the specification change be graphically visualized somehow in a UI or other interface? - -Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @webron" however at least one formal GitHub-based flow approval must be given. After voting criteria is met, any committer can merge the PR. No change should be approved until there is documentation for it, supplied in an accompanying PR. - -### Proposals for Specification Changes - -See [CONTRIBUTING.md](CONTRIBUTING.md) - -## Tracking Process - -* GitHub is the medium of record for all spec designs, use cases, and so on. - -* The **human readable** document is the source of truth. If using a JSON Schema again to document the spec, it is secondary to the human documentation. The documentation should live in a *.md file, in parallel to the latest document (versions/3.0.0.md for example). - -* At any given time, there would be *at most* 4 work branches. The branches would exist if work has started on them. Assuming a current version of 3.0.0: - - * main - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. - - * v3.0.1-dev - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. - - * v3.1.0 - The next MINOR version. - - * v4.0.0 - The next MAJOR version. - -* The main branch shall remain the current, released OpenAPI Specification. We will describe and link the work branch(es) on the **default** README.md on main. - -* Examples of how something is described *currently* vs. the proposed solution should accompany any change proposal. - -* New features should be done in feature branches/forks which, upon approval, are merged into the proper work branch. - -* Use labels for the workflow of specification changes. Examples of labels are proposed, housekeeping, migration-review, tooling-, needs documentation, review (candidate for upcoming TSC mtg), rejected, and needs approval. These labels must be assigned by project committers. Style is lowercase with dashes in place of spaces. - -* An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change. - -* A PR will be used to describe the *proposed* solution and linked to the original issue. - -* Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel. - -* When the work branch is ready and approved, the branch will be merged to main. - -## Release Process - -A release requires a vote on the 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 on the GitHub pull request for the release notes. TSC members are responsible for coordinating the actual merge to main with marketing support, if any. - -* 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) - -## Transparency - -The process should be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. General discussions should happen on the GitHub issues for this project. - -## Automated closure of issues Process - -See [CONTRIBUTING.md](CONTRIBUTING.md) - -## Automated TDC agenda issues Process - -See [CONTRIBUTING.md](CONTRIBUTING.md) - -## Participation - -While governance of the specification is the role of the TSC, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. - -## Community Roles - -While these developer community roles are informal, there are many ways to get involved with the OpenAPI community, such as: - -* Contributor: Includes but is not limited to any [contributor to the specification](https://github.com/OAI/OpenAPI-Specification/graphs/contributors) via an accepted pull request or who participates in issues or TSC calls. - -* Implementer: any person involved in the creation or maintenance of tooling that leverages the current OpenAPI Specification - -* Ambassador: represents the OpenAPI Specification to the developer community. This could be through talks at conferences or meetups, blog posts, or answering questions in places like Twitter, Stack Overflow, or the GitHub repo. - -* Supporter: uses the specification and appreciates its value. From 4a81dcb96aa0ebf49a5cb178082bc4006c77f30b Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 9 Dec 2024 15:59:38 +0000 Subject: [PATCH 4/8] Add the style guide as a separate file --- style-guide.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 style-guide.md diff --git a/style-guide.md b/style-guide.md new file mode 100644 index 0000000000..d43e977fcb --- /dev/null +++ b/style-guide.md @@ -0,0 +1,38 @@ +## 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" + + From 28c5df3e98b571a9a74b2839382c14b88bdbb5ed Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 10 Dec 2024 20:01:43 +0000 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Ralf Handl --- CONTRIBUTING.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dccdb21e4b..d29cd8e707 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,7 +68,7 @@ Most issues should have a clear outcome; something will be fixed, improved or ot We use [discussions](#discussions) for ideas and early-stage suggestions. -> ![NOTE] +> [!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. @@ -104,14 +104,14 @@ 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 pr port) for pull requests that repeat a change from one version to another +- [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 attention) automated tag when an issue is updated -- [Needs author feedback](https://github.com/OAI/OpenAPI-Specification/labels/Needs author feedback) used to indicate that more information is needed from the issue creator -- [No recent activity](https://github.com/OAI/OpenAPI-Specification/labels/No recent activity) if no information is received, the issue is marked for closure (automatic after 30 days) +- [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 @@ -163,13 +163,13 @@ Draft pull requests can still be reviewed while in draft state. ## Reviewers -> ![NOTE] +> [!NOTE] > See also the detailed team outlines in the [roles section](#roles). All pull requests must be reviewed and approved by one member of the TSC or Maintainer teams. Reviews from other contributors are always welcome. -Additionally, all pull requests that change the specification file `spec/oas.md` must be approved by 2 TSC members. +Additionally, all pull requests that change the specification file `spec/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. @@ -189,7 +189,7 @@ 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. +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: @@ -289,7 +289,7 @@ To get in touch with other people on the project, ask questions, or anything els - 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: Historical branch strategy +### 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). From 299291f717cf8b31c305483d6896321c3b950621 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 10 Dec 2024 20:05:17 +0000 Subject: [PATCH 6/8] Add better information about where the spec actually is in the repo --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d29cd8e707..b16393de3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,9 @@ All participants are expected to read and follow this code. 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. -The specification is in the file `spec/oas.md`. +Published versions of the specification are in the `versions/` folder. +The under-development versions of the specification are in the file `spec/oas.md` on the appropriately-versioned branch. +For example, work on the next patch release for 3.2 is on `v3.2-dev` in the file `spec/oas.md`. 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). From b9f244fe444548c5d8e452bfcf2271b845e8edd4 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 11 Dec 2024 20:17:02 +0000 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Ralf Handl --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b16393de3a..5803ad52af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,7 +85,7 @@ More information is in the [Appendix: Issue automation](#appendix-issue-automati 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), [Maintainer](#maintainer) and [TSC](#tsc) teams. +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. @@ -134,7 +134,7 @@ The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the spec > [!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 [Branches](#branches) section for more information about the updated branching strategy. +> 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. @@ -168,7 +168,7 @@ Draft pull requests can still be reviewed while in draft state. > [!NOTE] > See also the detailed team outlines in the [roles section](#roles). -All pull requests must be reviewed and approved by one member of the TSC or Maintainer teams. +All pull requests must be reviewed and approved by one member of the TSC or Maintainers teams. Reviews from other contributors are always welcome. Additionally, all pull requests that change the specification file `spec/oas.md` must be approved by two TSC members. From 77b6518608f2ee1cf900fe317544da3160e5b174 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 11 Dec 2024 20:35:57 +0000 Subject: [PATCH 8/8] Update markdown files from pull request feedback --- CONTRIBUTING.md | 8 ++++---- style-guide.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5803ad52af..af59315aeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Exceptions may be made when links to external URLs have been changed by a 3rd pa Published versions of the specification are in the `versions/` folder. The under-development versions of the specification are in the file `spec/oas.md` on the appropriately-versioned branch. -For example, work on the next patch release for 3.2 is on `v3.2-dev` in the file `spec/oas.md`. +For example, work on the next release for 3.2 is on `v3.2-dev` in the file `spec/oas.md`. 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). @@ -118,7 +118,7 @@ Labels related to [issue automation](#appendix-issue-automation) ### 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 milestone we expect they will be released in. +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. @@ -291,7 +291,7 @@ To get in touch with other people on the project, ask questions, or anything els - 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 +## 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). @@ -307,7 +307,7 @@ For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and e 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: diff --git a/style-guide.md b/style-guide.md index d43e977fcb..fc8fab8d0f 100644 --- a/style-guide.md +++ b/style-guide.md @@ -18,7 +18,7 @@ The following additional rules should be followed but currently are not enforced 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. +9. Use [Oxford commas](https://en.wikipedia.org/wiki/Serial_comma), avoid [Shatner commas](https://www.latimes.com/archives/blogs/jacket-copy/story/2011-06-30/goodbye-oxford-comma-hello-shatner-comma). 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.