|
| 1 | +# Contribute to the Arazzo Specification |
| 2 | + |
| 3 | +We welcome contributions and discussion. |
| 4 | +Bug reports and feature requests are welcome, please add an issue explaining your use case. |
| 5 | +Pull requests are also welcome, but it is recommended to create an issue first, to allow discussion. |
| 6 | + |
| 7 | +Questions and comments are also welcome - use the GitHub Discussions feature. |
| 8 | +You will also find notes from past meetings in the Discussion tab. |
| 9 | + |
| 10 | +## Key information |
| 11 | + |
| 12 | +This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme). |
| 13 | +All participants are expected to read and follow this code. |
| 14 | + |
| 15 | +No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder). |
| 16 | +Exceptions may be made when links to external documents have been changed by a 3rd party, in order to keep our documents accurate. |
| 17 | + |
| 18 | +Published versions of the specification are in the `versions/` folder. |
| 19 | +The under-development versions of the specification are in the file `src/arazzo.md` on the appropriately-versioned branch. |
| 20 | +For example, work on the next release for 1.1 is on `v1.1-dev` in the file `src/arazzo.md`. |
| 21 | + |
| 22 | +The [spec site](https://spec.openapis.org) is the source of truth for the Arazzo specification as it contains all the citations and author credits. |
| 23 | + |
| 24 | +The OpenAPI project (which Arazzo sits under) is almost entirely staffed by volunteers. |
| 25 | +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. |
| 26 | + |
| 27 | +### Active branches |
| 28 | + |
| 29 | +The current active specification releases are: |
| 30 | + |
| 31 | +| Version | Branch | Notes | |
| 32 | +| ------- | ------ | ----- | |
| 33 | +| 1.0.2 | `v1.0-dev` | active patch release line | |
| 34 | +| 1.1.0 | `v1.1-dev` | minor release in development | |
| 35 | + |
| 36 | +## Pull Requests |
| 37 | + |
| 38 | +Pull requests are always welcome but please read the section below on [branching strategy](#branching-strategy) before you start. |
| 39 | + |
| 40 | +Pull requests MUST come from a fork; create a fresh branch on your fork based on the target branch for your change. |
| 41 | + |
| 42 | +### Branching Strategy |
| 43 | + |
| 44 | +Overview of branches: |
| 45 | + |
| 46 | +- `main` holds the published versions of the specification, utility scripts and supporting documentation. |
| 47 | +- `dev` is for development infrastructure and other changes that apply to multiple versions of development. |
| 48 | +- Branches named `vX.Y-dev` are the active development branches for future releases. |
| 49 | +- Branches name `vX.Y.Z-rel` are release branches (including when Z == 0). They exist 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. |
| 50 | + |
| 51 | +> All changes should be applied to the _earliest_ branch where the changes are relevant in the first instance. |
| 52 | +
|
| 53 | +## Release Process and Scope |
| 54 | + |
| 55 | +### Minor Releases |
| 56 | + |
| 57 | +Our roadmap for Arazzo releases is community-driven, meaning the specification is open for proposed additions by anyone. |
| 58 | + |
| 59 | +Changes in minor releases (such as 1.1) meet the following criteria: |
| 60 | + |
| 61 | +- Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version. |
| 62 | + For example, new optional fields can be added. |
| 63 | +- Drive quality-of-life improvements to support how Arazzo is used by practitioners, so that Arazzo evolves to continue to meet user needs. |
| 64 | + For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification. |
| 65 | +- Make the specification document clearer or easier to understand. |
| 66 | + |
| 67 | +A minor release is due when there are some meaningful features (including one or a small number of headline features). |
| 68 | + |
| 69 | +### Patch Releases |
| 70 | + |
| 71 | +Patch releases reflect a constant quest for improving the active minor versions of Arazzo. |
| 72 | +Since we do not edit specification documents after publication, even the smallest change has to be in a new release. |
| 73 | + |
| 74 | +Changes in patch releases meet the following criteria: |
| 75 | + |
| 76 | +- Editorial changes such as spelling or formatting fixes, including link updates. |
| 77 | +- Clarifications or additions that do not change the meaning of the specification. |
| 78 | + |
| 79 | +Patch releases are created as often as there are changes to the specification worth releasing. |
| 80 | + |
| 81 | +## Get in touch |
| 82 | + |
| 83 | +To get in touch with other people on the project, ask questions, or anything else: |
| 84 | + |
| 85 | +- Find us [on the OpenAPI Slack](https://communityinviter.com/apps/open-api/openapi) and join the `#arazzo` channel. |
| 86 | +- Start a [GitHub Discussion](https://github.com/OAI/Arazzo-Specification/discussions/). |
| 87 | +- Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/Arazzo-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHouse-keeping). |
| 88 | + |
| 89 | +## Appendix |
| 90 | + |
| 91 | +### Build the HTML version to publish |
| 92 | + |
| 93 | +We use ReSpec to render the markdown specification as HTML for publishing and easier reading. |
| 94 | +These instructions explain how you can build the HTML locally. |
| 95 | + |
| 96 | +You will need NodeJS 18 or later. |
| 97 | + |
| 98 | +Install dependencies: |
| 99 | + |
| 100 | +```sh |
| 101 | +npm install |
| 102 | +``` |
| 103 | + |
| 104 | +Produce stand-alone HTML files in the local `deploy/arazzo` folder: |
| 105 | + |
| 106 | +```sh |
| 107 | +npm run build |
| 108 | +``` |
| 109 | + |
| 110 | +Note that Linux users may need to add `--no-sandbox` to run `npx respec` as found in the `scripts/md2html/build.sh` file. |
0 commit comments