Add essential policies to DEVELOPMENT.md

[handrews]

In yet another attempt to prevent well-meaning people from opening PRs that we cannot accept. It turns out that if you make a PR template, it puts the template info below the commit message so people often don't see it.

[lornajane]

We could also name this file CONTRIBUTING to help users find it in a standard location (see https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) - I assume the convention is newer than the original structure of this project.

[lornajane]

It's a commitment to update the list of open branches, but I think it's worth it since we have to type it into half the pull requests we get anyway. I made a small suggestion, happy to review again at any time.

[lornajane]

I'd discourage adding time-sensitive content into a file we will probably continue to fail to update. Directing people to slack is the right thing in almost every case of confusion!

[handrews]

@lornajane yeah... I'm not sure what to do here. This file is huge, and a lot of it needs rewriting. I'd almost rather delete everything that's not current. Better to have undefined processes that documentation that is, at this point, outright wrong.

[handrews]

@lornajane I'd be quite happy to move it to CONTRIBUTING. I thought we had one that was used for something else, but we have CONTRIBUTORS. Which is also not used in a normal way as it's the TSC list, not the contributor list.

I'm also hesitant to add time-sensitive information, but like you said, we have to type it in so often anyway, at least this way we could point to an "official" document. I've noticed not everyone will go to Slack, much less ask a question there.

[karenetheridge]

This doesn't sound right because there are a number of schema changes in the v3.1.1-dev branch (mostly fixes to restore conformance with the spec).

[karenetheridge]

Also - could there/should there be an automated script that updates the json file immediately after a merged change to the yaml file?

[handrews]

This doesn't sound right because there are a number of schema changes in the v3.1.1-dev branch (mostly fixes to restore conformance with the spec).

I think those are ones that got merged by accident because someone didn't see that the branch was wrong. Although for 3.2 you are probably right, as it will get a new schema (but patch releases do not). Honestly, I'm not sure, I'm kind of trying to provoke some sort of clear policy.

Also - could there/should there be an automated script that updates the json file immediately after a merged change to the yaml file?

That would be great, but would require someone to do it. We could use forward-porting scripts that are more per-change oriented than the ones in the scripts directory and automation to forward-port individual PRs as well.

[karenetheridge]

I think those are ones that got merged by accident because someone didn't see that the branch was wrong.

I believe they were intentional.. there was even a new interim release made of the revised schema (about a year ago now) - "$id": "https://spec.openapis.org/oas/3.1/schema/2022-10-07". There have been enough commits since then that we could have another interim release now.

[lornajane]

I am not sure I've ever read this whole page before, we can definitely lose some of it! Your additions are a good enhancement so let's start there. I still think we should avoid the time-sensitive disclaimer, but without it, I'm happy and the other changes can follow.

[lornajane]

This is very good as it stands, thanks for adding it!

[AxelNennker]

The two tables "Current branches and documents open to change" and https://github.com/OAI/OpenAPI-Specification/blob/4a11c66836f7e3a0b9246a98849428bbc55ea8fd/DEVELOPMENT.md#tracking-process seem to be at odds.

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.

[handrews]

@lornajane @AxelNennker 's comment is why I had that disclaimer... :/

Since it's approved, I'm going to merge this and then someone with more time than me can reconcile it.