Skip to content

Commit 4d08775

Browse files
committed
Update CONTRIBUTING.md for current practices
* Explain current issue, milestone, and PR process * Explain how I-Ds may be published without a new meta-schema * Explain how meta-schemas may be updated in place * We do not keep the "master" branch publication-ready, aside from how it should always build and therefore could techncially be submitted. But the paragraph made it sound like "master" should make sense as a publishable draft which is definitely not always the case.
1 parent 04ee335 commit 4d08775

File tree

1 file changed

+21
-7
lines changed

1 file changed

+21
-7
lines changed

CONTRIBUTING.md

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,17 @@
22

33
## Issues
44

5-
Issues should identify an problem, enhancement, or use case; and propose some course of action for the draft. For alternate support channels, [see the json-schema.org website](http://json-schema.org/).
5+
Issues should identify an problem, enhancement, or use case; and propose some course of action for the draft. For alternate support channels, [see the json-schema.org website](http://json-schema.org/) or the [jsonschema tag on stackoverflow](https://stackoverflow.com/tags/jsonschema).
66

7-
Issues waiting for user feedback will be tagged "Feedback". Up to two weeks will be given for feedback to be provided.
7+
## Milestones
88

9-
If there seems to be consensus around an issue, the issue will be taken up (and tagged with a milestone) or closed.
9+
Each milestone is an estimation of the work that will be done for the next draft. Milestones are typically named after the meta-schema draft number, and the *open* milestone with the lowest draft number is the current active project.
10+
11+
Issues may be removed from a milestoned due to lack of consensus, lack of anyone with the correct expertise to make a PR, or simply because we wish to publish a draft and defer the remaining issues to the next draft.
12+
13+
Numbered milestones other than the lowest-numbered one are used to tentatively organize future work, but may be completely reorganized once work on that draft actually begins.
14+
15+
The `draft-future` milestone is for issues for which there is an agreement that they should be addressed, but no specific timeline.
1016

1117
## Pull requests
1218

@@ -18,13 +24,21 @@ Changes that would affect implementation behavior should typically be opened as
1824

1925
Pull requests should be made to master.
2026

21-
## Writing guidelines
27+
Most PRs, including all PRs that impact implementation behavior, will be left open for a minimum of 14 days. Minor wording fixes may be merged more quickly once approved by a project member.
28+
29+
## Internet-Drafts and meta-schemas
30+
31+
An Internet-Draft (I-D) publication replaces previous documents in their entirety.
32+
33+
I-D updates that are purely editorial bug fixes (with no implementation-impacting changes) will continue to use the same meta-schemas as the version that they fix.
34+
35+
I-D updates that impact behavior, whether as a bug fix or a new, changed, or removed feature, will have new meta-schemas published along with them.
2236

23-
An Internet-Draft publication replaces previous documents in their entirety. Behavorial changes to the document should be reverse-compatible with existing written schemas, or allow for implementations to implement old and removed behavior.
37+
The meta-schema URI is used to differentiate between different vocabularies (currently only Validation and Hyper-Schema).
2438

25-
The meta-schema URI is used to differentiate between different vocabularies (Validation and Hyper-schema). The authority on JSON Schema behavior is the respective specification document, not the JSON meta-schema; the JSON version of the meta-schema is maintained in an informative capacity only. However, the meta-schema URI referred to in the document should desginate a fixed JSON document, and updates to this document should be publised at a new URI. Updates should be made to the meta-schema and published at a time when it becomes desirable for new behaviors and features to be described in this fashion.
39+
The authority on JSON Schema behavior is the respective specification document, not the JSON meta-schema; the JSON version of the meta-schema is maintained in an informative capacity only.
2640

27-
The "master" branch should always be Internet-Draft ready. The document editor is responsible for ensuring that the writing meets best practices for an I-D. An I-D will be published from "master" branch when wider review is desired, at the editor's discretion.
41+
As an informative document, bugs in the meta-schema may be fixed in place to align them with the normative specification. Examples of in-place fixes include adding an accidentally omitted keyword or fixing an incorrect type. By definition, no correct schema should fail validation against the meta-schema after a bug fix, although previously validating incorrect schemas may start to (correctly) fail validation.
2842

2943
## Conduct
3044

0 commit comments

Comments
 (0)