| YEP: | 1 |
|---|---|
| Title: | YEP Purpose and Guidelines |
| Authors: | Kyle Sunden, Blaise Thompson |
| Status: | accepted |
| Tags: | meta |
| Post-History: | 2020-04-22, 2020-04-23, 2020-07-02, 2020-07-05 |
YEP stands for "yaq enhancement proposal". YEPs are standards for use by the yaq ecosystem and community. YEPs provide concise technical specifications for features and processes.
We intend YEP to be the primary mechanism for proposing new features of yaq, and collecting community input. YEPs are meant as a way to garner consensus around an idea, and documenting dissenting opinions.
YEPs are markdown files stored in a git repository, and their revision history is the historical record of the proposal.
Enhancement proposal comes from the term as used by the Python community. In particular, python as a whole has PEPs. Similar processes are also used by numpy, matplotlib, and others.
YEP index numbers are assigned by the core team. In general, they will be assigned in ascending order, but exceptions may be made.
YEPs are roughly categorized by:
YEPs have only three available status codes:
YEPs can have tags to help categorize their behavior.
Current tags are:
meta: YEPs about YEPsstandard: YEPs which define standards an implementor would need to knowtrait: YEPs which define a TraitThe YEP submission project is not intended to be challenging, but is designed to encourage intentional, well reasoned changes to the yaq ecosystem. As such, there are a number of steps that should be taken in most cases.
If you have an idea for a new YEP, start by chatting with members of the community. The contact page provides ways to reach out to community members. It is generally a good idea to solicit feedback to ensure that the idea is both generally applicable and does not have any glaring negative consequences. This will help to define the scope and consider alternate approaches to the same problem. It can also save you time in the event that a similar idea was previously discussed and rejected (your idea may overcome the reasons it was rejected, but if it doesn't, there is no reason to spend time preparing a formal YEP).
YEPs are tracked in a GitLab repository. After getting initial feedback informally, you can start to write a formal specification. This occurs via a GitLab merge request. Submitters with commit privileges may simply branch, outside contributors must first fork the repository.
Within the yeps folder, copy yep-012.md into a new file with file name yep-XXX.md where XXX is the yep number.
You can suggest a number, but it may be changed prior to acceptance as a draft.
If you do not know, use 999.
Update the metadata, including the YEP title and your name in the author field.
Fill out he sections in the body of the YEP as you see fit.
Create an issue to discuss the YEP, and link to it in the Discussion section of the YEP. Finally, submit via a Merge Request.
The yaq team will start by giving a quick look at the file. Things like formatting errors and minor mistakes may be considered at this time, but importantly the initial review does not mean the YEP is final and accepted, only open for broader discussion.
We may reject the YEP at this stage. Grounds for dismissal include poorly defined scope/reasoning, significant backwards incompatibility, and duplication of effort.
This initial review may go back and forth to provide clarification. In particular, metadata in the Header should be largely correct and complete (aside from appending dates to the post-history, of course).
Once satisfied, the draft YEP will be merged, the YEP number will be fully claimed and permanent, and the open review period will begin.
In this stage, anybody in the community may comment on the YEP, with the YEP author responsible for responding to comments, and editing the text via additional merge requests. Most merge requests during this phase are likely to be accepted, but serve as way to trace the changes and resolution of discussion points.
The length period is not defined, lasting only long enough that the Core Team has a consensus, feels the community has had an opportunity to comment, and discussion points are resolved.
A Core Team member will open a Merge request changing the status of the YEP to "accepted" or "rejected". A different Core Team member will merge the request, and should do so with consensus of the core team.
Each YEP typically has the following parts:
YEP 012 is a template that makes remembering these sections easy. This is not a hard and fast rule, some YEPs may be more logically broken down into different sections.
Each YEP must begin with a header which includes metadata about the YEP:
---
yep: 1
title: YEP Purpose and Guidelines
author: Kyle Sunden
Blaise Thompson <blaise@untzag.com>
status: draft
tags: meta
post-history: 2020-04-22
2020-04-23
---
These headers are parsed by a library to help render the website and index page.
Please include the --- markers, and note that blank lines are NOT allowed in this block.
The YEP index number must be confirmed by a member of the core team, though you may suggest one.
The title should be short and descriptive.
The Status and tags are as described above.
Tags are newline delimited.
Authors are newline delimited, must be indented, and emails are optional.
Dates are in ISO 8601 format (date only) and are newline delimited.
Each YEP has a corresponding GitLab issue linked in the YEP. This issue is where discussion on the YEP should typically take place. If there are new discussion points, closed issues can be reopened. Additional issues regarding YEPs, if created should have their contents reproduced in the official discussion issue. However, if extended discussion takes place in an alternate issue, they should also be linked in the Discussion section of the YEP.
Updates are performed using GitLab Merge Requests to the yeps repository which update the markdown files in the yeps folder.
Updates to YEPs MUST achieve consensus among the core team.
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
built 2023-10-10 23:52:42 CC0: no copyright