Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add initial take at a more formalized JEP process #14

Closed
wants to merge 1 commit into from
Closed

Add initial take at a more formalized JEP process #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions 0000-jep-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
69 changes: 51 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand All @@ -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.