From 3fde35568e9099e61820e258073326fc193290cf Mon Sep 17 00:00:00 2001 From: Ryan Morshead Date: Sun, 16 Jul 2023 16:09:22 -0600 Subject: [PATCH] initial work on rpep-0000 --- .gitignore | 1 + README.md | 18 + docs/index.md | 0 docs/rpeps/RPEP-0000.md | 796 ++++++++++++++++++++++++++++++++++++++++ docs/template.md | 47 +++ mkdocs.yml | 62 ++++ pyproject.toml | 17 + 7 files changed, 941 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 docs/index.md create mode 100644 docs/rpeps/RPEP-0000.md create mode 100644 docs/template.md create mode 100644 mkdocs.yml create mode 100644 pyproject.toml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f29ea31 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.hatch diff --git a/README.md b/README.md new file mode 100644 index 0000000..7671f8d --- /dev/null +++ b/README.md @@ -0,0 +1,18 @@ +# ReactPy Enhancement Proposals (RPEPs) + +The repository contains documents that outline proposals for large changes to ReactPy. + +## Creating an RPEP + +- Install [Hatch](https://github.com/pypa/hatch) +- Clone this repository +- Run `hatch shell` +- Copy the [`template.md`](./blob/main/docs/template.md) into a new file at `docs/rpeps/RPEP-9999.md` +- Add it to the `nav` in [`mkdocs.yml`](./blob/main/mkdocs.yml) +- Fill out the template with your proposal +- See what it looks like by running `mkdocs serve` +- Create a pull request. + +## License + +`rpep` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/rpeps/RPEP-0000.md b/docs/rpeps/RPEP-0000.md new file mode 100644 index 0000000..17faa59 --- /dev/null +++ b/docs/rpeps/RPEP-0000.md @@ -0,0 +1,796 @@ +--- +title: RPEP-0000 +summary: What is an RPEP? +authors: + - Ryan Morshead +--- + +# Abstract + +RPEP stands for ReactPy Enhancement Proposal. An RPEP is a design +document providing information to the ReactPy community, or describing +a new feature for ReactPy or its processes or environment. The RPEP +should provide a concise technical specification of the feature and a +rationale for the feature. + +We intend RPEPs to be the primary mechanisms for proposing major new +features, for collecting community input on an issue, and for documenting +the design decisions that have gone into ReactPy. The RPEP author is +responsible for building consensus within the community and documenting +dissenting opinions. + +Because the RPEPs are maintained as text files in a versioned +repository, their revision history is the historical record of the +feature proposal. This historical record is available by the normal git +commands for retrieving older revisions, and can also be browsed +`on GitHub `\_\_. + +# RPEP Audience + +The typical primary audience for RPEPs are the core developers of the +ReactPy however, other parts of the ReactPy community may also choose to +use the process (particularly for Informational RPEPs) to document expected +API conventions and to manage complex design coordination problems that +require collaboration across multiple projects. + +# RPEP Types + +There are three kinds of RPEP: + +1. A **Specification** RPEP describes a new feature or standard for + ReactPy. It may also describe an interoperability standard that will + be supported outside of ReactPy versions before a subsequent RPEP + adds support in a future version of ReactPy. + +2. An **Informational** RPEP describes a ReactPy design issue, or + provides general guidelines or information to the ReactPy community, + but does not propose a new feature. Informational RPEPs do not + necessarily represent a ReactPy community consensus or + recommendation, so users and implementers are free to ignore + Informational RPEPs or follow their advice. + +3. A **Process** RPEP describes a process surrounding ReactPy, or + proposes a change to (or an event in) a process. Process RPEPs are + like Standards Track RPEPs but apply to areas other than the ReactPy + language itself. They may propose an implementation, but not to + ReactPy's codebase; they often require community consensus; unlike + Informational RPEPs, they are more than recommendations, and users + are typically not free to ignore them. Examples include + procedures, guidelines, changes to the decision-making process, and + changes to the tools or environment used in ReactPy development. + Any meta-RPEP is also considered a Process RPEP. + +## Start with an idea for ReactPy + +The RPEP process begins with a new idea for ReactPy. It is highly +recommended that a single RPEP contain a single key proposal or new +idea; the more focused the RPEP, the more successful it tends to be. +Most enhancements and bug fixes don't need an RPEP and +can be submitted directly to the +[ReactPy issue tracker](https://github.com/reactive-python/reactpy/issues). +The RPEP editors reserve the +right to reject RPEP proposals if they appear too unfocused or too +broad. If in doubt, split your RPEP into several well-focused ones. + +Each RPEP must have a champion -- someone who writes the RPEP using the style +and format described below, shepherds the discussions in the appropriate +forums, and attempts to build community consensus around the idea. The RPEP +champion (a.k.a. Author) should first attempt to ascertain whether the idea is +RPEP-able. Posting to the +[ReactPy Discussion Forum](https://github.com/reactive-python/reactpy/discussions) +is usually the best way to go about this, unless a more specialized venue is +appropriate. + +Vetting an idea publicly before going as far as writing an RPEP is meant +to save the potential author time. Many ideas have been brought +forward for changing ReactPy that have been rejected for various +reasons. Asking the ReactPy community first if an idea is original +helps prevent too much time being spent on something that is +guaranteed to be rejected based on prior discussions (searching +the internet does not always do the trick). It also helps to make sure +the idea is applicable to the entire community and not just the author. +Just because an idea sounds good to the author does not +mean it will work for most people in most areas where ReactPy is used. + +Once the champion has asked the ReactPy community as to whether an +idea has any chance of acceptance, a draft RPEP should be presented to +the appropriate venue mentioned above. +This gives the author a chance to flesh out the draft +RPEP to make properly formatted, of high quality, and to address +initial concerns about the proposal. + +## Submitting an RPEP + +Following the above initial discussion, the workflow varies based on whether +any of the RPEP's co-authors are core developers. If one or more of the RPEP's +co-authors are core developers, they are responsible for following the process +outlined below. Otherwise (i.e. none of the co-authors are core developers), +then the RPEP author(s) will need to find a sponsor for the RPEP. + +Ideally, a core developer sponsor is identified, but non-core sponsors may also +be selected with the approval of the Steering Council. Members of the GitHub +"RPEP editors" team are pre-approved to be sponsors. The sponsor's job is to +provide guidance to the RPEP author to help them through the logistics of the +RPEP process (somewhat acting like a mentor). Being a sponsor does **not** +disqualify that person from becoming a co-author or RPEP-Delegate later on (but +not both). The sponsor of an RPEP is recorded in the "Sponsor:" field of the +header. + +Once the sponsor or the core developer(s) co-authoring the RPEP deem the RPEP +ready for submission, the proposal should be submitted as a draft RPEP via a +`GitHub pull request`\_. The draft must be written in RPEP style as described +below, else it will fail review immediately (although minor errors may be +corrected by the editors). + +The standard RPEP workflow is: + +- You, the RPEP author, fork the `RPEP repository`\_, and create a file named + :file:`RPEP-{NNNN}.rst` that contains your new RPEP. :samp:`{NNNN}` should be the next + available RPEP number not used by a published or in-PR RPEP. + +- In the "RPEP:" header field, enter the RPEP number that matches your filename + as your draft RPEP number. + +- In the "Type:" header field, enter "Standards Track", + "Informational", or "Process" as appropriate, and for the "Status:" + field enter "Draft". For full details, see `RPEP Header Preamble`\_. + +- Update `.github/CODEOWNERS`_ such that any co-author(s) or sponsors + with write access to the `RPEP repository`_ are listed for your new file. + This ensures any future pull requests changing the file will be assigned + to them. + +- Push this to your GitHub fork and submit a pull request. + +- The RPEP editors review your PR for structure, formatting, and other + errors. For a reST-formatted RPEP, :RPEP:`12` is provided as a template. + It also provides a complete introduction to reST markup that is used + in RPEPs. Approval criteria are: + + - It sound and complete. The ideas must make technical sense. The + editors do not consider whether they seem likely to be accepted. + - The title accurately describes the content. + - The RPEP's language (spelling, grammar, sentence structure, etc.) + and code style (examples should match :RPEP:`7` & :RPEP:`8`) should be + correct and conformant. The RPEP text will be automatically checked for + correct reStructuredText formatting when the pull request is submitted. + RPEPs with invalid reST markup will not be approved. + + Editors are generally quite lenient about this initial review, + expecting that problems will be corrected by the reviewing process. + **Note:** Approval of the RPEP is no guarantee that there are no + embarrassing mistakes! Correctness is the responsibility of authors + and reviewers, not the editors. + + If the RPEP isn't ready for approval, an editor will send it back to + the author for revision, with specific instructions. + +- Once approved, they will assign your RPEP a number. + +Once the review process is complete, and the RPEP editors approve it (note that +this is _not_ the same as accepting your RPEP!), they will squash commit your +pull request onto main. + +The RPEP editors will not unreasonably deny publication of an RPEP. Reasons for +denying RPEP status include duplication of effort, being technically unsound, +not providing proper motivation or addressing backwards compatibility, or not +in keeping with the ReactPy philosophy. The Steering Council can be consulted +during the approval phase, and are the final arbiter of a draft's RPEP-ability. + +Developers with write access to the `RPEP repository`_ may claim RPEP +numbers directly by creating and committing a new RPEP. When doing so, the +developer must handle the tasks that would normally be taken care of by the +RPEP editors (see `RPEP Editor Responsibilities & Workflow`_). This includes +ensuring the initial version meets the expected standards for submitting a +RPEP. Alternately, even developers should submit RPEPs via pull request. +When doing so, you are generally expected to handle the process yourself; +if you need assistance from RPEP editors, mention `@ReactPy/RPEP-editors` +on GitHub. + +As updates are necessary, the RPEP author can check in new versions if they +(or a collaborating developer) have write access to the `RPEP repository`\_. +Getting an RPEP number assigned early can be useful for ease of +reference, especially when multiple draft RPEPs are being considered at the +same time. + +Standards Track RPEPs consist of two parts, a design document and a +reference implementation. It is generally recommended that at least a +prototype implementation be co-developed with the RPEP, as ideas that sound +good in principle sometimes turn out to be impractical when subjected to the +test of implementation. + +## Discussing an RPEP + +As soon as an RPEP number has been assigned +and the draft RPEP is committed to the `RPEP repository`\_, +a discussion thread for the RPEP should be created +to provide a central place to discuss and review its contents, and the +RPEP should be updated so that the `Discussions-To` header links to it. + +The RPEP authors (or sponsor, if applicable) may select any reasonable venue +for the discussion, so long as the the following criteria are met: + +- The forum is appropriate to the RPEP's topic. +- The thread is publicly available on the web so that all interested parties + can participate. +- The discussion is subject to the `ReactPy Community Code of Conduct +`\_. +- A direct link to the current discussion thread is provided in the RPEP + under the `Discussions-To` header. + +The `RPEPs category`_ of the `ReactPy Discourse`_ +is the preferred choice for most new RPEPs, +whereas historically the `ReactPy-Dev`_ mailing list was commonly used. +Some specialized topics have specific venues, such as +`Typing-SIG`_ for typing RPEPs or the `Packaging category`\_ on the ReactPy +Discourse for packaging RPEPs. If the RPEP authors are unsure of the best venue, +the RPEP Sponsor and RPEP editors can advise them accordingly. + +If an RPEP undergoes a significant re-write or other major, substantive +changes to its proposed specification, a new thread should typically be created +in the chosen venue to solicit additional feedback. If this occurs, the +`Discussions-To` link must be updated and a new `Post-History` entry added +pointing to this new thread. + +If it is not chosen as the discussion venue, +a brief announcement post should be made to the `RPEPs category`\_ +with at least a link to the rendered RPEP and the `Discussions-To` thread +when the draft RPEP is committed to the repository +and if a major-enough change is made to trigger a new thread. + +RPEP authors are responsible for collecting community feedback on an RPEP +before submitting it for review. However, to avoid long-winded and +open-ended discussions, strategies such as soliciting private or more +narrowly-tailored feedback in the early design phase, +collaborating with other community members with expertise in the RPEP's +subject matter, and picking an appropriately-specialized discussion for the +RPEP's topic (if applicable) should be considered. +RPEP authors should use their discretion here. + +Once the RPEP is assigned a number and committed to the RPEP repository, +substantive issues should generally be discussed on the canonical public +thread, as opposed to private channels, GitHub pull request reviews or +unrelated venues. This ensures everyone can follow and contribute, +avoids fragmenting the discussion, +and makes sure it is fully considered as part of the RPEP review process. +Comments, support, concerns and other feedback on this designated thread +are a critical part of what the Steering Council or RPEP-Delegate will +consider when reviewing the RPEP. + +## RPEP Review & Resolution + +Once the authors have completed an RPEP, they may request a review for +style and consistency from the RPEP editors. +However, content review and acceptance of the RPEP is ultimately the +responsibility of the Steering Council, which is formally initiated by +opening a `Steering Council issue`\_ once the authors (and sponsor, if any) +determine the RPEP is ready for final review and resolution. + +To expedite the process in selected cases (e.g. when a change is clearly +beneficial and ready to be accepted, but the RPEP hasn't been formally submitted +for review yet), the Steering Council may also initiate an RPEP review, first +notifying the RPEP author(s) and giving them a chance to make revisions. + +The final authority for RPEP approval is the Steering Council. However, whenever +a new RPEP is put forward, any core developer who believes they are suitably +experienced to make the final decision on that RPEP may offer to serve as its +RPEP-Delegate by `notifying the Steering Council `\_ +of their intent. If the Steering Council approves their offer, +the RPEP-Delegate will then have the authority to approve or reject that RPEP. + +The term "RPEP-Delegate" is used under the Steering Council governance model +for the RPEP's designated decision maker, +who is recorded in the "RPEP-Delegate" field in the RPEP's header. +The term "BDFL-Delegate" is a deprecated alias for RPEP-Delegate, a legacy of +the time when when ReactPy was led by `a BDFL `\_. +Any legacy references to "BDFL-Delegate" should be treated as equivalent to +"RPEP-Delegate". + +An individual offering to nominate themselves as an RPEP-Delegate must notify +the relevant authors and (when present) the sponsor for the RPEP, and submit +their request to the Steering Council +(which can be done via a `new issue `\_ ). +Those taking on this responsibility are free to seek +additional guidance from the Steering Council at any time, and are also expected +to take the advice and perspectives of other core developers into account. + +The Steering Council will generally approve such self-nominations by default, +but may choose to decline them. +Possible reasons for the Steering Council declining a +self-nomination as RPEP-Delegate include, but are not limited to, perceptions of +a potential conflict of interest (e.g. working for the same organisation as the +RPEP submitter), or simply considering another potential RPEP-Delegate to be +more appropriate. If core developers (or other community members) have concerns +regarding the suitability of an RPEP-Delegate for any given RPEP, they may ask +the Steering Council to review the delegation. + +If no volunteer steps forward, then the Steering Council will approach core +developers (and potentially other ReactPy community members) with relevant +expertise, in an attempt to identify a candidate that is willing to serve as +RPEP-Delegate for that RPEP. If no suitable candidate can be found, then the +RPEP will be marked as Deferred until one is available. + +Previously appointed RPEP-Delegates may choose to step down, or be asked to step +down by the Council, in which case a new RPEP-Delegate will be appointed in the +same manner as for a new RPEP (including deferral of the RPEP if no suitable +replacement can be found). In the event that an RPEP-Delegate is asked to step +down, this will overrule any prior acceptance or rejection of the RPEP, and it +will revert to Draft status. + +When such standing delegations are put in place, the Steering Council will +maintain sufficient public records to allow subsequent Councils, the core +developers, and the wider ReactPy community to understand the delegations that +currently exist, why they were put in place, and the circumstances under which +they may no longer be needed. + +For an RPEP to be accepted it must meet certain minimum criteria. It +must be a clear and complete description of the proposed enhancement. +The enhancement must represent a net improvement. The proposed +implementation, if applicable, must be solid and must not complicate +the interpreter unduly. Finally, a proposed enhancement must be +"ReactPyic" in order to be accepted by the Steering Council. (However, +"ReactPyic" is an imprecise term; it may be defined as whatever is acceptable to +the Steering Council. This logic is intentionally circular.) See :RPEP:`2` +for standard library module acceptance criteria. + +Except where otherwise approved by the Steering Council, +pronouncements of RPEP resolution will be posted to the +`RPEPs category`_ on the `ReactPy Discourse`_. + +Once an RPEP has been accepted, the reference implementation must be +completed. When the reference implementation is complete and incorporated +into the main source code repository, the status will be changed to "Final". + +To allow gathering of additional design and interface feedback before committing +to long term stability for a language feature or standard library API, an RPEP +may also be marked as "Provisional". This is short for "Provisionally Accepted", +and indicates that the proposal has been accepted for inclusion in the reference +implementation, but additional user feedback is needed before the full design +can be considered "Final". Unlike regular accepted RPEPs, provisionally accepted +RPEPs may still be Rejected or Withdrawn _even after the related changes have +been included in a ReactPy release_. + +Wherever possible, it is considered preferable to reduce the scope of a proposal +to avoid the need to rely on the "Provisional" status (e.g. by deferring some +features to later RPEPs), as this status can lead to version compatibility +challenges in the wider ReactPy ecosystem. :RPEP:`411` provides additional details +on potential use cases for the Provisional status. + +an RPEP can also be assigned the status "Deferred". The RPEP author or an +editor can assign the RPEP this status when no progress is being made +on the RPEP. Once an RPEP is deferred, an RPEP editor can reassign it +to draft status. + +an RPEP can also be "Rejected". Perhaps after all is said and done it +was not a good idea. It is still important to have a record of this +fact. The "Withdrawn" status is similar - it means that the RPEP author +themselves has decided that the RPEP is actually a bad idea, or has +accepted that a competing proposal is a better alternative. + +When an RPEP is Accepted, Rejected or Withdrawn, the RPEP should be updated +accordingly. In addition to updating the Status field, at the very least +the Resolution header should be added with a direct link +to the relevant post making a decision on the RPEP. + +RPEPs can also be superseded by a different RPEP, rendering the original +obsolete. This is intended for Informational RPEPs, where version 2 of +an API can replace version 1. + +The possible paths of the status of RPEPs are as follows: + +.. image:: RPEP-0001/process_flow.svg +:class: invert-in-dark-mode +:alt: RPEP process flow diagram + +While not shown in the diagram, "Accepted" RPEPs may technically move to +"Rejected" or "Withdrawn" even after acceptance. This will only occur if +the implementation process reveals fundamental flaws in the design that were +not noticed prior to acceptance of the RPEP. Unlike Provisional RPEPs, these +transitions are only permitted if the accepted proposal has _not_ been included +in a ReactPy release - released changes must instead go through the regular +deprecation process (which may require a new RPEP providing the rationale for +the deprecation). + +Some Informational and Process RPEPs may also have a status of "Active" +if they are never meant to be completed. E.g. :RPEP:`1` (this RPEP). + +## RPEP Maintenance + +In general, RPEPs are no longer substantially modified after they have reached +the Accepted, Final, Rejected or Superseded state. Once resolution is reached, +an RPEP is considered a historical document rather than a living specification. +Formal documentation of the expected behavior should be maintained elsewhere, +such as the `Language Reference`_ for core features, the `Library Reference`_ +for standard library modules or the `PyPA Specifications`\_ for packaging. + +If changes based on implementation experience and user feedback are made to +Standards track RPEPs while in the Provisional or (with SC approval) Accepted +state, they should be noted in the RPEP, such that the RPEP accurately describes +the implementation at the point where it is marked Final. + +Active (Informational and Process) RPEPs may be updated over time to reflect +changes to development practices and other details. The precise process +followed in these cases will depend on the nature and purpose of the RPEP +in question. + +Occasionally, a Deferred or even a Withdrawn RPEP may be resurrected +with major updates, but it is often better to just propose a new one. + +# What belongs in a successful RPEP? + +Each RPEP should have the following parts/sections: + +1. Preamble -- :rfc:`2822` style headers containing meta-data about the + RPEP, including the RPEP number, a short descriptive title (limited + to a maximum of 44 characters), the names, and optionally the + contact info for each author, etc. + +2. Abstract -- a short (~200 word) description of the technical issue + being addressed. + +3. Motivation -- The motivation is critical for RPEPs that want to + change the ReactPy language, library, or ecosystem. It should + clearly explain why the existing language specification is + inadequate to address the problem that the RPEP solves. This can + include collecting documented support for the RPEP from important + projects in the ReactPy ecosystem. RPEP submissions without + sufficient motivation may be rejected. + +4. Rationale -- The rationale fleshes out the specification by + describing why particular design decisions were made. It should + describe alternate designs that were considered and related work, + e.g. how the feature is supported in other languages. + + The rationale should provide evidence of consensus within the + community and discuss important objections or concerns raised + during discussion. + +5. Specification -- The technical specification should describe the + syntax and semantics of any new language feature. The + specification should be detailed enough to allow competing, + interoperable implementations for at least the current major ReactPy + platforms (ReactPy, Jython, IronReactPy, PyPy). + +6. Backwards Compatibility -- All RPEPs that introduce backwards + incompatibilities must include a section describing these + incompatibilities and their severity. The RPEP must explain how the + author proposes to deal with these incompatibilities. RPEP + submissions without a sufficient backwards compatibility treatise + may be rejected outright. + +7. Security Implications -- If there are security concerns in relation + to the RPEP, those concerns should be explicitly written out to make + sure reviewers of the RPEP are aware of them. + +8. How to Teach This -- For an RPEP that adds new functionality or changes + language behavior, it is helpful to include a section on how to + teach users, new and experienced, how to apply the RPEP to their + work. + + This section may include key points and recommended documentation + changes that would help users adopt a new feature or migrate their + code to use a language change. + +9. Reference Implementation -- The reference implementation must be + completed before any RPEP is given status "Final", but it need not + be completed before the RPEP is accepted. While there is merit + to the approach of reaching consensus on the specification and + rationale before writing code, the principle of "rough consensus + and running code" is still useful when it comes to resolving many + discussions of API details. + + The final implementation must include test code and documentation + appropriate for either the ReactPy language reference or the + standard library reference. + +10. Rejected Ideas -- Throughout the discussion of an RPEP, various ideas + will be proposed which are not accepted. Those rejected ideas should + be recorded along with the reasoning as to why they were rejected. + This both helps record the thought process behind the final version + of the RPEP as well as preventing people from bringing up the same + rejected idea again in subsequent discussions. + + In a way this section can be thought of as a breakout section of the + Rationale section that is focused specifically on why certain ideas + were not ultimately pursued. + +11. Open Issues -- While an RPEP is in draft, ideas can come up which + warrant further discussion. Those ideas should be recorded so people + know that they are being thought about but do not have a concrete + resolution. This helps make sure all issues required for the RPEP to be + ready for consideration are complete and reduces people duplicating + prior discussion. + +12. Footnotes -- A collection of footnotes cited in the RPEP, and + a place to list non-inline hyperlink targets. + +13. Copyright/license -- Each new RPEP must be placed under a dual license of + public domain and CC0-1.0-Universal\_ (see this RPEP for an example). + +# RPEP Formats and Templates + +RPEPs are UTF-8 encoded text files using the reStructuredText\_ format. +reStructuredText allows for rich markup that is still quite easy to +read, but also results in good-looking and functional HTML. :RPEP:`12` +contains instructions and a :RPEP:`RPEP template <12#suggested-sections>`. + +The RPEP text files are automatically +`converted to HTML `** +(via a `Sphinx `\_-based :RPEP:`build system <676>`) +for easier `online reading `**. + +# RPEP Header Preamble + +Each RPEP must begin with an :rfc:`2822` style header preamble. The headers +must appear in the following order. Headers marked with "\*" are +optional and are described below. All other headers are required. + +.. code-block:: text + + RPEP: + Title: + Author: + +- Sponsor: +- RPEP-Delegate: + Discussions-To: + Status: + Type: +- Topic: +- Content-Type: text/x-rst +- Requires: + Created: +- ReactPy-Version: + Post-History: +- Replaces: +- Superseded-By: +- Resolution: + +The Author header lists the names, and optionally the email addresses +of all the authors/owners of the RPEP. The format of the Author header +values must be: + +.. code-block:: text + + Random J. User + +if the email address is included, and just: + +.. code-block:: text + + Random J. User + +if the address is not given. + +If there are multiple authors, each should be on a separate line +following :rfc:`2822` continuation line conventions. Note that personal +email addresses in RPEPs will be obscured as a defense against spam +harvesters. + +The Sponsor field records which developer (core, or otherwise approved by the +Steering Council) is sponsoring the RPEP. If one of the authors of the RPEP is a +core developer then no sponsor is necessary and thus this field should be left +out. + +The RPEP-Delegate field is used to record the individual appointed by the +Steering Council to make the final decision on whether or not to approve or +reject an RPEP. (The delegate's email address is currently omitted due to a +limitation in the email address masking for reStructuredText RPEPs) + +_Note: The Resolution header is required for Standards Track RPEPs +only. It contains a URL that should point to an email message or +other web resource where the pronouncement about +(i.e. approval or rejection of) the RPEP is made._ + +The Discussions-To header provides the URL to the current +canonical discussion thread for the RPEP. +For email lists, this should be a direct link to the thread in the list's +archives, rather than just a mailto: or hyperlink to the list itself. + +The Type header specifies the type of RPEP: Standards Track, +Informational, or Process. + +The optional Topic header lists the special topic, if any, +the RPEP belongs under. +See the :ref:`topic-index` for the existing topics. + +The format of an RPEP is specified with a Content-Type header. +All RPEPs must use reStructuredText (see :RPEP:`12`), +and have a value of `text/x-rst`, the default. +Previously, plaintext RPEPs used `text/plain` (see :RPEP:`9`). + +The Created header records the date that the RPEP was assigned a +number, while Post-History is used to record the dates of and corresponding +URLs to the Discussions-To threads for the RPEP, with the former as the +linked text, and the latter as the link target. +Both sets of dates should be in `dd-mmm-yyyy` format, e.g. `14-Aug-2001`. + +Standards Track RPEPs will typically have a ReactPy-Version header which +indicates the version of ReactPy that the feature will be released with. +Standards Track RPEPs without a ReactPy-Version header indicate +interoperability standards that will initially be supported through +external libraries and tools, and then potentially supplemented by a later RPEP +to add support to the standard library. Informational and Process RPEPs do +not need a ReactPy-Version header. + +RPEPs may have a Requires header, indicating the RPEP numbers that this +RPEP depends on. + +RPEPs may also have a Superseded-By header indicating that an RPEP has +been rendered obsolete by a later document; the value is the number of +the RPEP that replaces the current document. The newer RPEP must have a +Replaces header containing the number of the RPEP that it rendered +obsolete. + +# Auxiliary Files + +RPEPs may include auxiliary files such as diagrams. Such files should be +named `RPEP-XXXX-Y.ext`, where "XXXX" is the RPEP number, "Y" is a +serial number (starting at 1), and "ext" is replaced by the actual +file extension (e.g. "png"). + +Alternatively, all support files may be placed in a subdirectory called +`RPEP-XXXX`, where "XXXX" is the RPEP number. When using a subdirectory, there +are no constraints on the names used in files. + +# Changing Existing RPEPs + +Draft RPEPs are freely open for discussion and proposed modification, at the +discretion of the authors, until submitted to the Steering Council or +RPEP-Delegate for review and resolution. Substantive content changes should +generally be first proposed on the RPEP's discussion thread listed in its +`Discussions-To` header, while copyedits and corrections can be submitted +as a `GitHub issue`_ or `GitHub pull request`_. +RPEP authors with write access to the RPEP repository can update the RPEPs +themselves by using `git push` or a GitHub PR to submit their changes. +For guidance on modifying other RPEPs, consult the `RPEP Maintenance`\_ section. + +See the `Contributing Guide`\_ for additional details, and when in doubt, +please check first with the RPEP author and/or an RPEP editor. + +# Transferring RPEP Ownership + +It occasionally becomes necessary to transfer ownership of RPEPs to a +new champion. In general, it is preferable to retain the original author as +a co-author of the transferred RPEP, but that's really up to the +original author. A good reason to transfer ownership is because the +original author no longer has the time or interest in updating it or +following through with the RPEP process, or has fallen off the face of +the 'net (i.e. is unreachable or not responding to email). A bad +reason to transfer ownership is because the author doesn't agree with the +direction of the RPEP. One aim of the RPEP process is to try to build +consensus around an RPEP, but if that's not possible, an author can always +submit a competing RPEP. + +If you are interested in assuming ownership of an RPEP, you can also do this via +pull request. Fork the `RPEP repository`\_, make your ownership modification, +and submit a pull request. You should mention both the original author and +`@ReactPy/RPEP-editors` in a comment on the pull request. (If the original +author's GitHub username is unknown, use email.) If the original author +doesn't respond in a timely manner, the RPEP editors will make a +unilateral decision (it's not like such decisions can't be reversed :). + +# RPEP Editor Responsibilities & Workflow + +an RPEP editor must be added to the `@ReactPy/RPEP-editors` group on GitHub and +must watch the `RPEP repository`\_. + +Note that developers with write access to the `RPEP repository`\_ may +handle the tasks that would normally be taken care of by the RPEP editors. +Alternately, even developers may request assistance from RPEP editors by +mentioning `@ReactPy/RPEP-editors` on GitHub. + +For each new RPEP that comes in an editor does the following: + +- Make sure that the RPEP is either co-authored by a core developer, has a core + developer as a sponsor, or has a sponsor specifically approved for this RPEP + by the Steering Council. + +- Read the RPEP to check if it is ready: sound and complete. The ideas + must make technical sense, even if they don't seem likely to be + accepted. + +- The title should accurately describe the content. + +- The file name extension is correct (i.e. `.rst`). + +- Ensure that everyone listed as a sponsor or co-author of the RPEP who has write + access to the `RPEP repository`_ is added to `.github/CODEOWNERS`_. + +- Skim the RPEP for obvious defects in language (spelling, grammar, + sentence structure, etc.), and code style (examples should conform to + :RPEP:`7` & :RPEP:`8`). Editors may correct problems themselves, but are + not required to do so (reStructuredText syntax is checked by the repo's CI). + +- If a project is portrayed as benefiting from or supporting the RPEP, make sure + there is some direct indication from the project included to make the support + clear. This is to avoid an RPEP accidentally portraying a project as supporting + an RPEP when in fact the support is based on conjecture. + +If the RPEP isn't ready, an editor will send it back to the author for +revision, with specific instructions. If reST formatting is a +problem, ask the author(s) to use :RPEP:`12` as a template and resubmit. + +Once the RPEP is ready for the repository, an RPEP editor will: + +- Check that the author has selected a valid RPEP number or assign them a + number if they have not (almost always just the next available number, but + sometimes it's a special/joke number, like 666 or 3141). + + Remember that numbers below 100 are meta-RPEPs. + +- Check that the author has correctly labeled the RPEP's type + ("Standards Track", "Informational", or "Process"), and marked its + status as "Draft". + +- Ensure all CI build and lint checks pass without errors, + and there are no obvious issues in the rendered preview output. + +- Merge the new (or updated) RPEP. + +- Inform the author of the next steps (open a discussion thread and + update the RPEP with it, post an announcement, etc). + +Updates to existing RPEPs should be submitted as a `GitHub pull request`\_. + +Many RPEPs are written and maintained by developers with write access +to the ReactPy codebase. The RPEP editors monitor the RPEP repository +for changes, and correct any structure, grammar, spelling, or +markup mistakes they see. + +RPEP editors don't pass judgment on RPEPs. They merely do the +administrative & editorial part (which is generally a low volume task). + +Resources: + +- `Index of ReactPy Enhancement Proposals `\_ + +- `Following ReactPy's Development +`\_ + +- `ReactPy Developer's Guide `\_ + +# Footnotes + +.. \_.github/CODEOWNERS: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +.. \_ReactPy issue tracker: https://github.com/ReactPy/ReactPy/issues + +.. \_CC0-1.0-Universal: https://choosealicense.com/licenses/cc0-1.0/ + +.. \_reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html + +.. \_RPEP repository: https://github.com/ReactPy/RPEPs + +.. \_GitHub pull request: https://github.com/ReactPy/RPEPs/pulls + +.. \_GitHub issue: https://github.com/ReactPy/RPEPs/issues + +.. \_Steering Council issue: https://github.com/ReactPy/steering-council/issues/new/choose + +.. \_ReactPy-Dev: https://mail.ReactPy.org/mailman3/lists/ReactPy-dev.ReactPy.org/ + +.. \_ReactPy Discourse: https://discuss.ReactPy.org/ + +.. \_Ideas category: https://discuss.ReactPy.org/c/ideas/ + +.. \_RPEPs category: https://discuss.ReactPy.org/c/RPEPs/ + +.. \_Typing-SIG: https://mail.ReactPy.org/mailman3/lists/typing-sig.ReactPy.org/ + +.. \_Packaging category: https://discuss.ReactPy.org/c/packaging/ + +.. \_Language Reference: https://docs.ReactPy.org/3/reference/index.html + +.. \_Library Reference: https://docs.ReactPy.org/3/library/index.html + +.. \_PyPA Specifications: https://packaging.ReactPy.org/en/latest/specifications/ + +.. \_Contributing Guide: https://github.com/ReactPy/RPEPs/blob/main/CONTRIBUTING.rst + +# Copyright + +This document is placed in the public domain or under the +CC0-1.0-Universal license, whichever is more permissive. diff --git a/docs/template.md b/docs/template.md new file mode 100644 index 0000000..11c422e --- /dev/null +++ b/docs/template.md @@ -0,0 +1,47 @@ +# RPEP-9999 - Subtitle + +A short (~200 word) description of the technical issue being addressed. + +# Motivation + +Clearly explain why the existing features of ReactPy is not inadequate to address the problem that the RPEP solves. + +# Rationale + +Describe why particular design decisions were made. + +# Specification + +Describe the details of any new feature. + +# Backwards Compatibility + +Describe potential impact and severity on pre-existing code. + +# Security Implications + +How could a malicious user take advantage of this new feature? + +# How to Teach This + +How to teach users, new and experienced, how to apply the RPEP to their work. + +# Reference Implementation + +Link to any existing implementation and details about its state, e.g. proof-of-concept. + +# Rejected Ideas + +Why certain ideas that were brought while discussing this PEP were not ultimately pursued. + +# Open Issues + +Any points that are still being decided/discussed. + +# Footnotes + +A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets. + +# Copyright + +This document is placed in the public domain or under the MIT license. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..5b65354 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,62 @@ +--- +nav: + - Home: index.md + - Proposals: + - RPEP-0000: rpeps/RPEP-0000.md + - Template: template.md + +theme: + name: material + palette: + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/white-balance-sunny + name: Switch to light mode + primary: light blue + accent: light blue + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/weather-night + name: Switch to dark mode + primary: black + features: + - navigation.instant + - navigation.tabs + - navigation.top + - content.code.copy + icon: + repo: fontawesome/brands/github + logo: https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg + favicon: https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg + +markdown_extensions: + - toc: + permalink: true + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight: + linenums: true + - pymdownx.superfences + - pymdownx.details + - pymdownx.inlinehilite + - admonition + - attr_list + - md_in_html + - pymdownx.keys + +plugins: + - search + - section-index + +site_name: ReactPy +site_description: ReactPy Enhancement Proposals +copyright: Copyright © 2023 Reactive Python +repo_url: https://github.com/reactive-python/rpeps +site_url: https://reactive-python.github.io/rpeps +repo_name: reactive-python/rpeps +edit_uri: edit/main diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..71a42ab --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,17 @@ +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "rpeps" +version = "0.0.0" +description = 'ReactPy Enhancement Proposals' +requires-python = ">=3.7" +license = "MIT" +dependencies = [ + "mkdocs", + "mkdocs-material", + "mkdocs-git-authors-plugin", + "mkdocs-minify-plugin", + "mkdocs-section-index", +]