Governance: Document development/enhancement process for Arazzo

[frankkilcommins]

Create a DEVELOPMENT.md to describe the appropriate process for making patch, minor, major changes to the Arazzo Specification.

Review/consult with @oai/tsc

[handrews]

@frankkilcommins because

1. Most github repos now use CONTRIBUTING.md instead of DEVELOPMENT.md
2. The OAI/OpenAPI-Specification DEVELOPMENT.md is so out-of-date that no one even knows where to start to fix it

on a recent TDC call we decided to start a CONTRIBUTING.md (which I should do right now actually) and begin filling it out with up-to-date guidance and deleting things from DEVELOPMENT.md

So I would recommend a CONTRIBUTING.md here instead.

[frankkilcommins]

@handrews completely agree. If we're updating the process to move towards a CONTRIBUTING.md then even better. We'll follow suit here.

My main aim is to quickly define the rules needed to ensure that we can move forward safely now that we've published 1.0.0. I've created https://github.com/OAI/Arazzo-Specification/tree/v1.0.0-dev for working on patches/typos (of which some have been spotted, so want to get them fixed asap).

[handrews]

@frankkilcommins here's the PR for starting up CONTRIBUTING in the OAS repo:

• Begin DEVELOPMENT.md -> CONTRIBUTING.md OpenAPI-Specification#3984

[handrews]

@frankkilcommins That PR I linked above include issue links to various topics under discussion, including the plan to move away from having both a separate branch and a separate file for each version. Because doing that makes it incredibly difficult to use git to manage multiple release lines. idk if you want to try to start that process here, but it's worth cosidering. Especially if you want to start on 1.1.0 while also doing a 1.0.1:

• Define and document branch strategy for the spec, both development and publishing OpenAPI-Specification#3677
• Define and document our schema publishing process OpenAPI-Specification#3715

[frankkilcommins]

Small update here. @handrews is making great progress on OAI/OpenAPI-Specification#3677 and detailing out the future process for OAS.

I'll work with Henry to see if we can align a similar process for Arazzo from this point on and in advance of merging v1.0.0-dev changes into main and creating a patch release.

[frankkilcommins]

Following along from the work from @handrews within the OAS repo, we'll be adopting a similar branching/release strategy for Arazzo.

As the current v1.0.0-dev branch is not in an aligned state some interim work needs to happen to conform to the process for the 1.0.1 patch release. Nevertheless much of the end state process can be followed.

The changes to move from v1.0.0-dev to the new process and release 1.0.1 are as follows:

• Fix v1.0.0-dev work to move changes from 1.0.0.md to src/arazzo.md (all on my fork via the following commands):
  • git mv versions/1.0.0.md src/arazzo.md
  • git restore --staged versions/1.0.0.md
  • git restore versions/1.0.0.md
• Restore 1.0.0.md from main via git checkout origin/main -- versions/1.0.0.md (all on my fork)
• Create appropriate branches on Arazzo repo
  • dev (from current main) and rename 1.0.0.md to src/arazzo.md
  • v1.0-dev (from dev)
• Create PR and merge changes from v1.0.0-dev (myfork) to v1.0-dev and dev
• Create release branch v1.0.1-rel from v1.0-dev
• Rename src/arazzo.md to versions/1.0.1.md and merge v1.0.1-rel to main
• Review published HTML versions
• Create release tag/notes in GitHub (main)
• Create v1.1-dev from dev (from the commit that v1.0-dev was merged into main)
• Clean up old / non process related branches from repo
• Create and merge Contributing.md on main and merge into relevant branches

Other related work being done:

• Update the infrastructure jobs/scripts to deploy multi versions (mostly done)
• Update the publishing jobs to leverage symbolic links (done - merged PR from Ralph)