You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 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.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+21-7Lines changed: 21 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -2,11 +2,17 @@
2
2
3
3
## Issues
4
4
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).
6
6
7
-
Issues waiting for user feedback will be tagged "Feedback". Up to two weeks will be given for feedback to be provided.
7
+
## Milestones
8
8
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.
10
16
11
17
## Pull requests
12
18
@@ -18,13 +24,21 @@ Changes that would affect implementation behavior should typically be opened as
18
24
19
25
Pull requests should be made to master.
20
26
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.
22
36
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).
24
38
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.
26
40
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.
0 commit comments