Skip to content

Commit

Permalink
Pull in README from original updates
Browse files Browse the repository at this point in the history
Sync changes from #14.

Closes #14.
  • Loading branch information
jamesls committed Mar 17, 2023
1 parent 39976f5 commit 4ea9cb4
Showing 1 changed file with 54 additions and 14 deletions.
68 changes: 54 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,25 @@
# 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
(http://jmespath.org/specification.html) requires a JEP.
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

You can review the existing JEPs in this repo to get a sense of the type
of changes that require a JEP.

## Things that do not need a JEP

Expand All @@ -34,10 +35,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 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).
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 during the review process.
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.

### Tenets of JMESPath

Expand Down

0 comments on commit 4ea9cb4

Please sign in to comment.