From d2d2a165d9ae287255a778977e5625c60c693e0f Mon Sep 17 00:00:00 2001 From: James Saryerwinnie Date: Tue, 24 May 2022 15:07:14 -0400 Subject: [PATCH] Add initial take at a more formalized JEP process I'm sure this will evolve over time so I wanted to start with as lightweight a process as possible. --- 0000-jep-template.md | 68 +++++++++++++++++++++++++++++++++++++++++++ README.md | 69 ++++++++++++++++++++++++++++++++------------ 2 files changed, 119 insertions(+), 18 deletions(-) create mode 100644 0000-jep-template.md diff --git a/0000-jep-template.md b/0000-jep-template.md new file mode 100644 index 0000000..d3509c9 --- /dev/null +++ b/0000-jep-template.md @@ -0,0 +1,68 @@ +# Your Feature Name + +- JEP: (leave blank) +- Author: Your name/alias +- Created: YYYY-MM-DD + + +# Abstract +[abstract]: #abstract + +A brief one paragraph description of what's being proposed. + + +# Motivation +[motivation]: #motivation + +Describe why this feature is needed in JMESPath. What are examples +of querying JSON documents that aren't possible unless JMESPath +adds support for this feature. + +JEPs that do not have sufficient motivation or interest will not be +accepted no matter how well written the proposal is or how simple +the feature may be. Use this section to make a compelling case why +JMESPath needs this feature. + + +# Specification +[specification]: #specification + +Write this section as if you were adding it to the existing +JMESPath spec, which is what will happen if the JEP is accepted. + +The following subsections are optional, and can be omitted if +they do not apply. + + +## Grammar Updates + +If you are proposing changes to the language itself, you must provide +the relevant ABNF updates to the grammar of the language. Any new +grammar rules as well as any modifications to existing grammar rules. + + +# Rationale +[rationale]: #rationale + +This section is used to explain why the proposed specification is the +best way to achieve the desired functionality. This is different from +the motivation section which explains why the feature should exist. + +You can add additional subsections as you feel necessary. Common +subsections here include: + +* Alternatives considered. Why were all the alternative designs that + were considered not chosen? What makes the proposed design of this + feature the best option? +* Tradeoffs made for this feature. +* Open and/or unresolved issues with the design. +* FAQ of anticipated review questions. If you anticipate specific + feedback from JEP reviewers you can add a FAQ subsection to help + streamline the review process. + +# Test Cases +[testcases]: #testcases + +Add test cases that use the test schema in the [jmespath.test](https://github.com/jmespath/jmespath.test) +repo. If the JEP is accepted, these test cases will be copied over to the +jmespath.test repo. diff --git a/README.md b/README.md index 9822d52..d8d0a38 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,21 @@ # JMESPath Enhancement Proposals -Any changes to the JMESPath specification -(http://jmespath.org/specification.html) must have a JEP (JMESPath Enhancement -Proposal) which is tracked in this repo. There are implementations of JMESPath -in over 9 different languages, and we want to make sure that any modifications -to the spec make sense for all JMESPath libraries. A JEP helps to work through -the design process for new additions and ensures that the JMESPath community -has a chance to give feedback before it's officially part of the specification. - +The JMESPath Enhancement Proposals (JEP) process is used to modify the +JMESPath language and specification. There are implementations of JMESPath +in over 10 languages, and this process ensures stakeholders and community +members have the opportunity to review and provide feedback before it's +officially part of the specification. ## Things that need a JEP -Any functionaly change that would require an update to the specification +Any functional change that would require an update to the specification (http://jmespath.org/specification.html) requires a JEP. This includes, but is not limited to: * New syntax * New functions -* New semantics/functionality +* New semantics ## Things that do not need a JEP @@ -34,14 +31,49 @@ make sure to reference prior proposals and explain why this new proposal should be considered despite similar proposals not being accepted. Writing a JEP can be a lot of work, so it can help to get initial guidance -before getting too far. You can chat on the JMESPath gitter channel -(https://gitter.im/jmespath/chat) to get an initial pulse of a new feature. +before going too far. A well thought out, high quality JEP helps its chance +of acceptance and helps ensure a productive review process. + +Before writing a JEP, you can create an issue for initial high level feedback +in order to get a sense of the likelihood of a JEP being accepted. You +can also use that issue to gauge interest in the feature. + +## The JEP Process + +1. Fork [this repository](https://github.com/jmespath/jmespath.jep). +2. Copy `0000-jep-template.md` to `proposals/0000-feature-name.md`, + where `feature-name` is a high level descriptive name of the + proposal. You don't need to add a JEP number, one will be + assigned if the JEP is accepted. +3. Fill in all sections of the JEP template. Be mindful of the + "Motivation" and "Rationale" sections. These are an important + part of driving concensus for a JEP. +4. Submit a pull request to this repo. +5. The JEP will be reviewed and feedback will be provided. Proposals + often go through several rounds of feedback, this is a normal and + expected part of the process. +6. As you incorporate feedback, do not rebase your commits. This ensures + the history and evolution of the proposal remains visible. +7. The discussions will eventually stabilize to one of several states: + + * The JEP has concensus for both the functionality and the + proposed specification and is ready to be accepted. + * The JEP has concensus for the feature but there is not concensus + with the specification. + * The JEP does not have concensus for the feature. + * The JEP loses steam and the discussions go stale. This will result + in the PR being closed, but is subject to being reopened by anyone + that wants to continue working on the JEP. + +8. Once the JEP is approved by the JMESPath core team the pull request + will be merged. + +9. The relevant parts of the "Specification" section will be added to the + JMESPath specification, and the tests cases from the "Test Cases" section + of the JEP will be added to the [jmespath.test](https://github.com/jmespath/jmespath.test) repo. + +10. JMESPath libraries can now implement the accepted JEP. -You can also create an issue in this repo with a rough proposal -to get initial high level feedback. Keep in mind that creating -an issue is only for initial feedback. If you'd like to move -forward with the proposal you will still need to write a JEP -and send a pull request (PR). ### Tenets of JMESPath @@ -51,4 +83,5 @@ these tenets gives your proposal a higher likelihood of being accepted: * JMESPath is not specific to a particular programming language. Avoid constructs that are difficult to implement in another language. * JMESPath strives to have one way to do something. -* Features are driven from real world use cases. +* Features are driven from real world use cases. New additions to the + language must demonstrate sufficient interest.