From 13b9a03fd826834f20d4c8ec85972c12950ae7e3 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Fri, 20 Oct 2023 11:50:18 -0400 Subject: [PATCH 01/84] phep-0001: initial port of Google doc * Version discussed on PyHC telecon 2023-10-16, with all "suggestions" applied * Does not incorporate discussion from the telecon --- pheps/phep-0001.md | 250 +++++++++++++ pheps/phep-0001/process_flow.svg | 580 +++++++++++++++++++++++++++++++ 2 files changed, 830 insertions(+) create mode 100644 pheps/phep-0001.md create mode 100644 pheps/phep-0001/process_flow.svg diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md new file mode 100644 index 0000000..f9a2cdf --- /dev/null +++ b/pheps/phep-0001.md @@ -0,0 +1,250 @@ +# PHEP 1 - PHEP Purpose and Guidelines +# What is a PHEP? +PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the PyHC community, or describing a new standard for Python or its processes or environment. The PHEP should provide a concise technical specification of the feature and a rationale for the feature. + +We intend PHEPs to be the primary mechanisms for proposing major new standards, for collecting community input on an issue, and for documenting the design decisions that have gone into PyHC standards and recommendations. The PHEP author is responsible for building consensus within the community and documenting dissenting opinions. + +Because the PHEPs 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. + +# PHEP Audience +The typical primary audience for PHEPs are the developers of PyHC packages, as well as developers of other implementations of the Python language specification. + +However, other parts of the PyHC community may also choose to use the process (particularly for Informational PHEPs) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects. + +# PHEP Types +There are three kinds of PHEP: + +1. A **Standards** Track PHEP describes a new standard for PyHC packages. +2. An **Informational** PHEP describes a PyHC design issue, or provides general guidelines or information to the PyHC community, but does not propose a new standard. Informational PHEPs do not necessarily represent a PyHC community consensus or recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. +3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to (or an event in) a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, 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 PyHC development or other Community activities. Any meta-PHEP is also considered a Process PHEP. + +# PHEP Applicability +**Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally should do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for approval. Standards track PHEP compliance should be considered as a factor in evaluating current and potential PyHC packages. + +**Informational** PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. + +**Process** PHEPs determine the process by which the PyHC community makes formal decisions and as such bind all participants in PyHC. + +# PHEP Workflow +## PHEP Editors +The PHEP editors are individuals responsible for managing the administrative and editorial aspects of the PHEP workflow (e.g. assigning PHEP numbers and changing their status). See [PHEP Editor Responsibilities & Workflow](#phep-editor-responsibilities-workflow) for details. + +PHEP editorship is by invitation of the current editors, and they can be contacted by mentioning `@python/pep-editors` on GitHub. All of the PHEP workflow can be conducted via the GitHub PHEP repository issues and pull requests. The initial set of editors are designated by consensus at the PyHC community meeting where PHEP 1 was proposed. + +## Start with an idea +The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. + +Each PHEP must have a champion – someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Posting to the PyHC mailing list or Element is usually the best way to go about this. + +Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. + +Once the champion has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft PHEP to make properly formatted, of high quality, and to address initial concerns about the proposal. + +## Submitting a PHEP +The proposal should be submitted as a draft PHEP via a [GitHub pull request](https://github.com/python/peps/pulls). The draft must be written in PHEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors). + +The standard PHEP workflow is: + +* You, the PHEP author, fork the PHEP repository, and create a file named `pep-9999.rst` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). +* Update [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) such that any co-author(s) or sponsors with write access to the PHEP 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 PHEP editors review your PR for structure, formatting, and other errors. For a reST-formatted PHEP, PHEP 12 is provided as a template. It also provides a complete introduction to reST markup that is used in PHEPs. Approval criteria are: + * It is 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 PHEP’s language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs 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 PHEP is no guarantee that there are no embarrassing mistakes! Correctness is the responsibility of authors and reviewers, not the editors. + + If the PHEP 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 PHEP a number. All PHEPs are sequentially-numbered at time of assignment. This includes meta-PHEPs. "Special" numbers (X, 0, etc.) are not used. + +Once the review process is complete, and the PHEP editors approve it (note that this is not the same as accepting your PHEP!), they will squash commit your pull request onto main. + +The PHEP editors will not unreasonably deny publication of a PHEP. Reasons for denying PHEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the PyHC philosophy. + +Standards Track PHEPs may consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation in an existing or new PyHC package be co-developed with the PHEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation. + +## Discussing a PHEP +As soon as a PHEP number has been assigned and the draft PHEP is committed to the PHEP repository, a discussion thread for the PHEP should be created to provide a central place to discuss and review its contents, and the PHEP should be updated so that the `Discussions-To` header links to it. + +The PHEP 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 PHEP’s topic. +* The thread is publicly available on the web so that all interested parties can participate. +* The discussion is subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). +* A direct link to the current discussion thread is provided in the PHEP under the `Discussions-To` header. + +The PyHC mailing list is the preferred choice for most new PHEPs. + +If a PHEP 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. + +PHEP authors are responsible for collecting community feedback on a PHEP 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 PHEP’s subject matter, and picking an appropriately-specialized discussion for the PHEP’s topic (if applicable) should be considered. PHEP authors should use their discretion here. + +Once the PHEP is assigned a number and committed to the PHEP 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 PHEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the community will consider when reviewing the PHEP. + +## PHEP Review & Resolution +Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community once the authors (and sponsor, if any) determine the PHEP is ready for final review and resolution. A PHEP is accepted when approved by consensus of attendees (virtual or in-person) at both a PyHC biweekly telecon and a biennial PyHC meeting with no edits to the PHEP occurring in between. Potential approval of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via email or Element chat, ensuring that the PHEP author is notified. + +For a PHEP 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 "pythonic" in order to be accepted by the community. (However, "pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) + +Pronouncements of PHEP resolution will be posted to the PHEPs category on the Python Discourse. + +Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project’s 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, a PHEP 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 PHEPs, provisionally accepted PHEPs may still be Rejected or Withdrawn. + +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 PHEPs), as this status can lead to version compatibility challenges in the wider PyHC ecosystem. + +A PHEP can also be assigned the status "Deferred". The PHEP author or an editor can assign the PHEP this status when no progress is being made on the PHEP. Once a PHEP is deferred, a PHEP editor can reassign it to draft status. + +A PHEP 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 PHEP author themselves has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. + +When a PHEP is Accepted, Rejected or Withdrawn, the PHEP 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 PHEP. + +PHEPs can also be superseded by a different PHEP, rendering the original obsolete. This is intended for Informational PHEPs, where version 2 of an API can replace version 1. + +The possible paths of the status of PHEPs are as follows: + +![PHEP status flow diagram](phep-0001/process_flow.svg) + +While not shown in the diagram, "Accepted" PHEPs 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 PHEP. Unlike Provisional PHEPs, these transitions are only permitted if the accepted proposal has not been included in a Python release - released changes must instead go through the regular deprecation process (which may require a new PHEP providing the rationale for the deprecation). + +## PHEP Maintenance +In general, PHEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification. + +If changes based on implementation experience and user feedback are made to Standards track PHEPs while in the Provisional state, they should be noted in the PHEP, such that the PHEP accurately describes the implementation at the point where it is marked Final. + +Occasionally, a Deferred or even a Withdrawn PHEP may be resurrected with major updates, but it is often better to just propose a new one. + +# What belongs in a successful PHEP? +Each PHEP should have the following parts/sections: + +1. Preamble – [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing meta-data about the PHEP, including the PHEP 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 PHEPs that want to change the PyHC or ecosystem. It should clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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 standard. The specification should be detailed enough to allow competing, interoperable implementations. +6. Backwards Compatibility – All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. PHEP submissions without a sufficient backwards compatibility treatise may be rejected outright. +7. Security Implications – If there are security concerns in relation to the PHEP, those concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. +8. How to Teach This – For a PHEP that adds new functionality or changes behavior, it is helpful to include a section on how to teach users, new and experienced, how to apply the PHEP 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 PHEP is given status "Final", but it need not be completed before the PHEP 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 the relevant PyHC project(s). + +10. Rejected Ideas – Throughout the discussion of a PHEP, 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 PHEP 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 a PHEP 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 PHEP to be ready for consideration are complete and reduces people duplicating prior discussion. +12. Footnotes – A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. +13. Copyright/license – Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). + +# PHEP Formats and Templates +PHEPs 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. A future PHEP may include a template. + +The PHEP text files are automatically converted to HTML (via a Sphinx-based build system) for easier online reading. + +# PHEP Header Preamble + +Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) 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. + + PHEP: + Title: + Author: + Discussions-To: + Status: + Type: + * Content-Type: text/x-rst + * Requires: + Created: + Post-History: + * Replaces: + * Superseded-By: + * Resolution: + +The Author header lists the names, and optionally the email addresses of all the authors/owners of the PHEP. The format of the Author header values must be: + +`Random J. User ` + +if the email address is included, and just: + +`Random J. User` + +if the address is not given. + +If there are multiple authors, each should be on a separate line following [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions. Note that personal email addresses in PHEPs will be obscured as a defense against spam harvesters. + +The Discussions-To header provides the URL to the current canonical discussion thread for the PHEP. 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 PHEP: Standards Track, Informational, or Process. + +The optional Topic header lists the special topic, if any, the PHEP belongs under. See the Topic Index for the existing topics. + +The format of a PHEP is specified with a Content-Type header. All PHEPs must use reStructuredText, and have a value of `text/x-rst`, the default. + +The Created header records the date that the PHEP was assigned a number, while Post-History is used to record the dates of and corresponding URLs to the Discussions-To threads for the PHEP, 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`. + +PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP depends on. + +PHEPs may also have a Superseded-By header indicating that a PHEP has been rendered obsolete by a later document; the value is the number of the PHEP that replaces the current document. The newer PHEP must have a Replaces header containing the number of the PHEP that it rendered obsolete. + +# Auxiliary Files +PHEPs may include auxiliary files such as diagrams. Such files should be named `phep-XXXX-Y.ext`, where "XXXX" is the PHEP 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 `phep-XXXX`, where "XXXX" is the PHEP number. When using a subdirectory, there are no constraints on the names used in files. + +# Changing Existing PHEPs +Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be first proposed on the PHEP’s discussion thread listed in its `Discussions-To` header, while copyedits and corrections can be submitted as a GitHub issue or GitHub pull request. PHEP authors with write access to the PHEP repository can update the PHEPs themselves by using git push or a GitHub PR to submit their changes. For guidance on modifying other PHEPs, consult the PHEP Maintenance section. + +See the Contributing Guide for additional details, and when in doubt, please check first with the PHEP author and/or a PHEP editor. + +# Transferring PHEP Ownership +It occasionally becomes necessary to transfer ownership of PHEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, 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 PHEP 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that’s not possible, an author can always submit a competing PHEP. + +If you are interested in assuming ownership of a PHEP, you can also do this via pull request. Fork the PHEP repository, make your ownership modification, and submit a pull request. You should mention both the original author and `@python/pep-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 PHEP editors will make a unilateral decision (it’s not like such decisions can’t be reversed :). + +# PHEP Editor Responsibilities & Workflow + +A PHEP editor must be added to the `@python/pep-editors` group on GitHub and must watch the PHEP repository. + +Note that developers with write access to the PHEP repository may handle the tasks that would normally be taken care of by the PHEP editors. Alternately, even developers may request assistance from PHEP editors by mentioning `@python/pep-editors` on GitHub. + +For each new PHEP that comes in an editor does the following: + +* Read the PHEP 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 co-author of the PHEP who has write access to the PHEP repository is added to [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). +* Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.). Editors may correct problems themselves, but are not required to do so. +* If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. This is to avoid a PHEP accidentally portraying a project as supporting a PHEP when in fact the support is based on conjecture. + +If the PHEP 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 PHEP 12 as a template and resubmit. + +Once the PHEP is ready for the repository, a PHEP editor will: + +* Assign a PHEP number (almost always just the next available number, but sometimes it’s a special/joke number, like 666 or 3141). +* Check that the author has correctly labeled the PHEP’s type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft". +* Merge the new (or updated) PHEP. +* Inform the author of the next steps (open a discussion thread and update the PHEP with it, post an announcement, etc). + +Updates to existing PHEPs should be submitted as a GitHub pull request. + +PHEP editors don’t pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). + +# Copyright +This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. + +This document draws from: + +* +* +* diff --git a/pheps/phep-0001/process_flow.svg b/pheps/phep-0001/process_flow.svg new file mode 100644 index 0000000..a21ae5a --- /dev/null +++ b/pheps/phep-0001/process_flow.svg @@ -0,0 +1,580 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Provisional + + + + Draft + + + + Withdrawn + + + + Rejected + + + + Final + + + + Accepted + + + + Deferred + + + + Active + + + + Replaced + + + + + + + + + + + + + From 55f16c1c8bb996edccb6bcec736bf636d7e79060 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 23 Oct 2023 10:53:13 -0400 Subject: [PATCH 02/84] phep-0001: switch to Markdown format --- pheps/phep-0001.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index f9a2cdf..5e03bd4 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -45,14 +45,14 @@ The proposal should be submitted as a draft PHEP via a [GitHub pull request](htt The standard PHEP workflow is: -* You, the PHEP author, fork the PHEP repository, and create a file named `pep-9999.rst` that contains your new PHEP. Use "9999" as your draft PHEP number. +* You, the PHEP author, fork the PHEP repository, and create a file named `pep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). * Update [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) such that any co-author(s) or sponsors with write access to the PHEP 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 PHEP editors review your PR for structure, formatting, and other errors. For a reST-formatted PHEP, PHEP 12 is provided as a template. It also provides a complete introduction to reST markup that is used in PHEPs. Approval criteria are: +* The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is 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 PHEP’s language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid reST markup will not be approved. + * The PHEP’s language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid MD markup will not be approved; here "invalid" include Markdown which provides clearly unintended output (in the discretion of the editors). Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. **Note**: Approval of the PHEP is no guarantee that there are no embarrassing mistakes! Correctness is the responsibility of authors and reviewers, not the editors. @@ -148,9 +148,11 @@ Each PHEP should have the following parts/sections: 13. Copyright/license – Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). # PHEP Formats and Templates -PHEPs 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. A future PHEP may include a template. +PHEPs are UTF-8 encoded text files using the Markdown format. Markdown allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). -The PHEP text files are automatically converted to HTML (via a Sphinx-based build system) for easier online reading. +PHEPs should be restricted to the ASCII subset of UTF-8 where practicable. Examples of cases where it is not practicable include the inclusion of personal names. + +The PHEP text files are automatically rendered by the GitHub interface for easier online reading. The Markdown source is the version of record. # PHEP Header Preamble @@ -163,7 +165,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Status: Type: - * Content-Type: text/x-rst + * Content-Type: text/markdown; charset=UTF-8; variant=CommonMark * Requires: Created: Post-History: Date: Mon, 23 Oct 2023 11:22:13 -0400 Subject: [PATCH 03/84] phep-0001: remove provisional and deferred status --- pheps/phep-0001.md | 23 +- pheps/phep-0001/process_flow.svg | 406 ++++++------------------------- 2 files changed, 90 insertions(+), 339 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 5e03bd4..e7df52b 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -91,32 +91,30 @@ For a PHEP to be accepted it must meet certain minimum criteria. It must be a cl Pronouncements of PHEP resolution will be posted to the PHEPs category on the Python Discourse. -Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project’s source code repository, the status will be changed to "Final". +Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project’s source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately 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, a PHEP 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 PHEPs, provisionally accepted PHEPs may still be Rejected or Withdrawn. +If a PHEP requires additional design and interface feedback before committing to long term stability, it must remain in "Draft". Alternatively, its scope can be reduced (e.g. by deferring some features to later PHEPs). -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 PHEPs), as this status can lead to version compatibility challenges in the wider PyHC ecosystem. +If no progress is being made on the PHEP, the editor should consult the author. The author may resume work on the PHEP, [transfer it to another author](transferring-phep-ownership), or withdraw it. If the author takes none of these actions, the editor may choose to bring the PHEP to the community for approval or rejection in its current form. -A PHEP can also be assigned the status "Deferred". The PHEP author or an editor can assign the PHEP this status when no progress is being made on the PHEP. Once a PHEP is deferred, a PHEP editor can reassign it to draft status. +A PHEP can also be "Rejected" if it fails community approval and the author is not willing or able to modify it. 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 PHEP author themselves has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. -A PHEP 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 PHEP author themselves has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. +When a PHEP changes state, the PHEP text must 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 PHEP. -When a PHEP is Accepted, Rejected or Withdrawn, the PHEP 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 PHEP. - -PHEPs can also be superseded by a different PHEP, rendering the original obsolete. This is intended for Informational PHEPs, where version 2 of an API can replace version 1. +PHEPs can also be replaced by a different PHEP, rendering the original obsolete. The possible paths of the status of PHEPs are as follows: ![PHEP status flow diagram](phep-0001/process_flow.svg) -While not shown in the diagram, "Accepted" PHEPs 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 PHEP. Unlike Provisional PHEPs, these transitions are only permitted if the accepted proposal has not been included in a Python release - released changes must instead go through the regular deprecation process (which may require a new PHEP providing the rationale for the deprecation). +While not shown in the diagram, "Accepted" PHEPs 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 PHEP. ## PHEP Maintenance In general, PHEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification. -If changes based on implementation experience and user feedback are made to Standards track PHEPs while in the Provisional state, they should be noted in the PHEP, such that the PHEP accurately describes the implementation at the point where it is marked Final. +If changes based on implementation experience and user feedback are made to PHEPs while in the Accepted state, they should be noted in the PHEP, such that the PHEP accurately describes the implementation at the point where it is marked Final. -Occasionally, a Deferred or even a Withdrawn PHEP may be resurrected with major updates, but it is often better to just propose a new one. +Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. # What belongs in a successful PHEP? Each PHEP should have the following parts/sections: @@ -162,7 +160,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Title: Author: Discussions-To: - Status: Type: * Content-Type: text/markdown; charset=UTF-8; variant=CommonMark @@ -210,6 +208,7 @@ Draft PHEPs are freely open for discussion and proposed modification, at the dis See the Contributing Guide for additional details, and when in doubt, please check first with the PHEP author and/or a PHEP editor. # Transferring PHEP Ownership + It occasionally becomes necessary to transfer ownership of PHEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, 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 PHEP 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that’s not possible, an author can always submit a competing PHEP. If you are interested in assuming ownership of a PHEP, you can also do this via pull request. Fork the PHEP repository, make your ownership modification, and submit a pull request. You should mention both the original author and `@python/pep-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 PHEP editors will make a unilateral decision (it’s not like such decisions can’t be reversed :). diff --git a/pheps/phep-0001/process_flow.svg b/pheps/phep-0001/process_flow.svg index a21ae5a..e1f8ec3 100644 --- a/pheps/phep-0001/process_flow.svg +++ b/pheps/phep-0001/process_flow.svg @@ -1,20 +1,20 @@ + sodipodi:docname="process_flow.svg" + inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:dc="http://purl.org/dc/elements/1.1/"> @@ -31,234 +31,76 @@ - - - - - - - - - + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> - - - - - - + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> - - - - - - - - - - - - - - - - - - + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + inkscape:guide-bbox="true" + inkscape:pagecheckerboard="0" + inkscape:document-units="pt" + fit-margin-top="10" + fit-margin-left="10" + fit-margin-right="10" + fit-margin-bottom="10"> - - - Provisional - + transform="translate(-0.4375,-0.4375)"> + transform="translate(-4.1995713,-67.718796)"> + transform="translate(9.7802009,-54.67472)"> + transform="translate(3.0280457,-0.43747711)"> + transform="translate(-1.7323761,-1.7512073)"> Accepted - - - Deferred - - - Active - + id="flowPara4662" /> + transform="translate(0.052654,7.4090851)"> Replaced - - @@ -545,36 +317,16 @@ sodipodi:nodetypes="cc" inkscape:connector-curvature="0" id="path13775" - d="M 318.43082,27.538182 H 370.4781" + d="m 318.48347,27.493742 h 52.04728" style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker13779)" /> - + d="M 55.952823,47.554331 V 78.296985 H 187.50528" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.07879;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker15177)" /> - - - From d1e2d43870d946150bf5fea9c5bcd9d72109a390 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 23 Oct 2023 11:28:21 -0400 Subject: [PATCH 04/84] phep-0001: ASCII-fy --- pheps/phep-0001.md | 56 +++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index e7df52b..bb0f530 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -34,7 +34,7 @@ PHEP editorship is by invitation of the current editors, and they can be contact ## Start with an idea The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have a champion – someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Posting to the PyHC mailing list or Element is usually the best way to go about this. +Each PHEP must have a champion - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Posting to the PyHC mailing list or Element is usually the best way to go about this. Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. @@ -52,11 +52,11 @@ The standard PHEP workflow is: * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is 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 PHEP’s language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid MD markup will not be approved; here "invalid" include Markdown which provides clearly unintended output (in the discretion of the editors). + * The PHEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid MD markup will not be approved; here "invalid" include Markdown which provides clearly unintended output (in the discretion of the editors). Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. **Note**: Approval of the PHEP is no guarantee that there are no embarrassing mistakes! Correctness is the responsibility of authors and reviewers, not the editors. - If the PHEP isn’t ready for approval, an editor will send it back to the author for revision, with specific instructions. + If the PHEP 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 PHEP a number. All PHEPs are sequentially-numbered at time of assignment. This includes meta-PHEPs. "Special" numbers (X, 0, etc.) are not used. @@ -71,7 +71,7 @@ As soon as a PHEP number has been assigned and the draft PHEP is committed to th The PHEP 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 PHEP’s topic. +* The forum is appropriate to the PHEP's topic. * The thread is publicly available on the web so that all interested parties can participate. * The discussion is subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). * A direct link to the current discussion thread is provided in the PHEP under the `Discussions-To` header. @@ -80,7 +80,7 @@ The PyHC mailing list is the preferred choice for most new PHEPs. If a PHEP 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. -PHEP authors are responsible for collecting community feedback on a PHEP 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 PHEP’s subject matter, and picking an appropriately-specialized discussion for the PHEP’s topic (if applicable) should be considered. PHEP authors should use their discretion here. +PHEP authors are responsible for collecting community feedback on a PHEP 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 PHEP's subject matter, and picking an appropriately-specialized discussion for the PHEP's topic (if applicable) should be considered. PHEP authors should use their discretion here. Once the PHEP is assigned a number and committed to the PHEP 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 PHEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the community will consider when reviewing the PHEP. @@ -91,7 +91,7 @@ For a PHEP to be accepted it must meet certain minimum criteria. It must be a cl Pronouncements of PHEP resolution will be posted to the PHEPs category on the Python Discourse. -Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project’s source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final". +Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final". If a PHEP requires additional design and interface feedback before committing to long term stability, it must remain in "Draft". Alternatively, its scope can be reduced (e.g. by deferring some features to later PHEPs). @@ -119,31 +119,31 @@ Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basi # What belongs in a successful PHEP? Each PHEP should have the following parts/sections: -1. Preamble – [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing meta-data about the PHEP, including the PHEP 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 PHEPs that want to change the PyHC or ecosystem. It should clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. +1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing meta-data about the PHEP, including the PHEP 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 PHEPs that want to change the PyHC or ecosystem. It should clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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 standard. The specification should be detailed enough to allow competing, interoperable implementations. -6. Backwards Compatibility – All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. PHEP submissions without a sufficient backwards compatibility treatise may be rejected outright. -7. Security Implications – If there are security concerns in relation to the PHEP, those concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. -8. How to Teach This – For a PHEP that adds new functionality or changes behavior, it is helpful to include a section on how to teach users, new and experienced, how to apply the PHEP to their work. +5. Specification - The technical specification should describe the syntax and semantics of any new standard. The specification should be detailed enough to allow competing, interoperable implementations. +6. Backwards Compatibility - All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. PHEP submissions without a sufficient backwards compatibility treatise may be rejected outright. +7. Security Implications - If there are security concerns in relation to the PHEP, those concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. +8. How to Teach This - For a PHEP that adds new functionality or changes behavior, it is helpful to include a section on how to teach users, new and experienced, how to apply the PHEP 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 PHEP is given status "Final", but it need not be completed before the PHEP 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. +9. Reference Implementation - The reference implementation must be completed before any PHEP is given status "Final", but it need not be completed before the PHEP 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 the relevant PyHC project(s). -10. Rejected Ideas – Throughout the discussion of a PHEP, 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 PHEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions. +10. Rejected Ideas - Throughout the discussion of a PHEP, 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 PHEP 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 a PHEP 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 PHEP to be ready for consideration are complete and reduces people duplicating prior discussion. -12. Footnotes – A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. -13. Copyright/license – Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). +11. Open Issues - While a PHEP 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 PHEP to be ready for consideration are complete and reduces people duplicating prior discussion. +12. Footnotes - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. +13. Copyright/license - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). # PHEP Formats and Templates PHEPs are UTF-8 encoded text files using the Markdown format. Markdown allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). @@ -184,7 +184,7 @@ if the address is not given. If there are multiple authors, each should be on a separate line following [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions. Note that personal email addresses in PHEPs will be obscured as a defense against spam harvesters. -The Discussions-To header provides the URL to the current canonical discussion thread for the PHEP. 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 Discussions-To header provides the URL to the current canonical discussion thread for the PHEP. 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 PHEP: Standards Track, Informational, or Process. @@ -203,15 +203,15 @@ PHEPs may include auxiliary files such as diagrams. Such files should be named ` Alternatively, all support files may be placed in a subdirectory called `phep-XXXX`, where "XXXX" is the PHEP number. When using a subdirectory, there are no constraints on the names used in files. # Changing Existing PHEPs -Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be first proposed on the PHEP’s discussion thread listed in its `Discussions-To` header, while copyedits and corrections can be submitted as a GitHub issue or GitHub pull request. PHEP authors with write access to the PHEP repository can update the PHEPs themselves by using git push or a GitHub PR to submit their changes. For guidance on modifying other PHEPs, consult the PHEP Maintenance section. +Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be first proposed on the PHEP's discussion thread listed in its `Discussions-To` header, while copyedits and corrections can be submitted as a GitHub issue or GitHub pull request. PHEP authors with write access to the PHEP repository can update the PHEPs themselves by using git push or a GitHub PR to submit their changes. For guidance on modifying other PHEPs, consult the PHEP Maintenance section. See the Contributing Guide for additional details, and when in doubt, please check first with the PHEP author and/or a PHEP editor. # Transferring PHEP Ownership -It occasionally becomes necessary to transfer ownership of PHEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, 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 PHEP 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that’s not possible, an author can always submit a competing PHEP. +It occasionally becomes necessary to transfer ownership of PHEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, 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 PHEP 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that's not possible, an author can always submit a competing PHEP. -If you are interested in assuming ownership of a PHEP, you can also do this via pull request. Fork the PHEP repository, make your ownership modification, and submit a pull request. You should mention both the original author and `@python/pep-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 PHEP editors will make a unilateral decision (it’s not like such decisions can’t be reversed :). +If you are interested in assuming ownership of a PHEP, you can also do this via pull request. Fork the PHEP repository, make your ownership modification, and submit a pull request. You should mention both the original author and `@python/pep-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 PHEP editors will make a unilateral decision (it's not like such decisions can't be reversed :). # PHEP Editor Responsibilities & Workflow @@ -221,25 +221,25 @@ Note that developers with write access to the PHEP repository may handle the tas For each new PHEP that comes in an editor does the following: -* Read the PHEP 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. +* Read the PHEP 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. `.md`). * Ensure that everyone listed as a co-author of the PHEP who has write access to the PHEP repository is added to [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). * Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.). Editors may correct problems themselves, but are not required to do so. * If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. This is to avoid a PHEP accidentally portraying a project as supporting a PHEP when in fact the support is based on conjecture. -If the PHEP isn’t ready, an editor will send it back to the author for revision, with specific instructions. If Markdown formatting is a problem, ask the author(s) to resubmit. +If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. If Markdown formatting is a problem, ask the author(s) to resubmit. Once the PHEP is ready for the repository, a PHEP editor will: -* Assign a PHEP number (almost always just the next available number, but sometimes it’s a special/joke number, like 666 or 3141). -* Check that the author has correctly labeled the PHEP’s type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft". +* Assign a PHEP number (almost always just the next available number, but sometimes it's a special/joke number, like 666 or 3141). +* Check that the author has correctly labeled the PHEP's type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft". * Merge the new (or updated) PHEP. * Inform the author of the next steps (open a discussion thread and update the PHEP with it, post an announcement, etc). Updates to existing PHEPs should be submitted as a GitHub pull request. -PHEP editors don’t pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). +PHEP editors don't pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). # Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. From 9f3659f7420be89564cfb45203c765403b06c7b4 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 23 Oct 2023 11:41:53 -0400 Subject: [PATCH 05/84] phep-0001: make compliant with itself --- pheps/phep-0001.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index bb0f530..e9b6f64 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -1,4 +1,13 @@ -# PHEP 1 - PHEP Purpose and Guidelines +PHEP: 1 +Title: PHEP Purpose and Guidelines +Author: Jonathan Niehof +Discussions-To: +Status: Draft +Type: Process +Content-Type: text/markdown; charset=UTF-8; variant=CommonMark +Created: 20-Oct-2023 +Post-History: + # What is a PHEP? PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the PyHC community, or describing a new standard for Python or its processes or environment. The PHEP should provide a concise technical specification of the feature and a rationale for the feature. @@ -163,7 +172,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Status: Type: - * Content-Type: text/markdown; charset=UTF-8; variant=CommonMark + Content-Type: text/markdown; charset=UTF-8; variant=CommonMark * Requires: Created: Post-History: Date: Mon, 23 Oct 2023 12:08:10 -0400 Subject: [PATCH 06/84] phep-0001: document immutability * Use 'replace' consistently instead of 'supersede' --- pheps/phep-0001.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index e9b6f64..c3963ae 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -119,12 +119,15 @@ The possible paths of the status of PHEPs are as follows: While not shown in the diagram, "Accepted" PHEPs 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 PHEP. ## PHEP Maintenance -In general, PHEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification. + +PHEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected, Withdrawn, or Replaced state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. If changes based on implementation experience and user feedback are made to PHEPs while in the Accepted state, they should be noted in the PHEP, such that the PHEP accurately describes the implementation at the point where it is marked Final. Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. +Changes to PHEPs in the Final state are limited to the preamble1, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. + # What belongs in a successful PHEP? Each PHEP should have the following parts/sections: From e4a61528302aa8362b86ddf93ef3241360484e02 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 23 Oct 2023 12:31:46 -0400 Subject: [PATCH 07/84] phep-0001: editor approvals, role --- pheps/phep-0001.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index c3963ae..27b699e 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -36,9 +36,12 @@ There are three kinds of PHEP: # PHEP Workflow ## PHEP Editors + The PHEP editors are individuals responsible for managing the administrative and editorial aspects of the PHEP workflow (e.g. assigning PHEP numbers and changing their status). See [PHEP Editor Responsibilities & Workflow](#phep-editor-responsibilities-workflow) for details. -PHEP editorship is by invitation of the current editors, and they can be contacted by mentioning `@python/pep-editors` on GitHub. All of the PHEP workflow can be conducted via the GitHub PHEP repository issues and pull requests. The initial set of editors are designated by consensus at the PyHC community meeting where PHEP 1 was proposed. +PHEP editorship is by nomination of the current editors, subject to approval of the individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or a steering committee or other such group as appropriately designated. In the event there are fewer than two active editors, such authority may appoint editors from active participants in the community, sufficient to bring the total to two. + +The editors can be contacted by mentioning `@heliophysicsPy/pep-editors` on GitHub. All of the PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. ## Start with an idea The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. @@ -50,13 +53,13 @@ Vetting an idea publicly before going as far as writing a PHEP is meant to save Once the champion has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft PHEP to make properly formatted, of high quality, and to address initial concerns about the proposal. ## Submitting a PHEP -The proposal should be submitted as a draft PHEP via a [GitHub pull request](https://github.com/python/peps/pulls). The draft must be written in PHEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors). +The proposal should be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors). The standard PHEP workflow is: -* You, the PHEP author, fork the PHEP repository, and create a file named `pep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP number. +* You, the PHEP author, fork the PHEP repository, and create a file named `phep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). -* Update [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) such that any co-author(s) or sponsors with write access to the PHEP repository are listed for your new file. This ensures any future pull requests changing the file will be assigned to them. +* Update [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) such that any co-author(s) or sponsors with write access to the standards 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 PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. @@ -223,13 +226,13 @@ See the Contributing Guide for additional details, and when in doubt, please che It occasionally becomes necessary to transfer ownership of PHEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, 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 PHEP 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that's not possible, an author can always submit a competing PHEP. -If you are interested in assuming ownership of a PHEP, you can also do this via pull request. Fork the PHEP repository, make your ownership modification, and submit a pull request. You should mention both the original author and `@python/pep-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 PHEP editors will make a unilateral decision (it's not like such decisions can't be reversed :). +If you are interested in assuming ownership of a PHEP, you can also do this via pull request. Fork the `standards` repository, make your ownership modification, and submit a pull request. You should mention both the original author and `@heliophysicsPy/phep-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 PHEP editors will make a unilateral decision (it's not like such decisions can't be reversed :). # PHEP Editor Responsibilities & Workflow -A PHEP editor must be added to the `@python/pep-editors` group on GitHub and must watch the PHEP repository. +A PHEP editor must be added to the `@heliophysicsPy/pep-editors` group on GitHub and must watch the `standards` repository. -Note that developers with write access to the PHEP repository may handle the tasks that would normally be taken care of by the PHEP editors. Alternately, even developers may request assistance from PHEP editors by mentioning `@python/pep-editors` on GitHub. +Other community members with write access to the `standards` repository may handle the tasks that would normally be taken care of by the PHEP editors. Alternately, even those with write access may request assistance from PHEP editors by mentioning `@heliophysicsPy/phep-editors` on GitHub. For each new PHEP that comes in an editor does the following: @@ -251,7 +254,9 @@ Once the PHEP is ready for the repository, a PHEP editor will: Updates to existing PHEPs should be submitted as a GitHub pull request. -PHEP editors don't pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). +PHEP editors don't pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). They may participate in the community discussion of a PHEP but have no obligation to be advocates. + +Disagreements with editors must be mediated by those with the authority to approve editors (as documented in [PHEP editors](#phep-editors)) and they may impose sanctions, up to and including removal of the editor role. # PHEP 1 Approval From 2f7cfa0ef7f10456093f92f76e47bd0c6d3820d5 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 23 Oct 2023 12:36:56 -0400 Subject: [PATCH 08/84] phep-0001: persnickety notes on formatting/wording --- pheps/phep-0001.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 27b699e..c7c07dc 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -34,6 +34,8 @@ There are three kinds of PHEP: **Process** PHEPs determine the process by which the PyHC community makes formal decisions and as such bind all participants in PyHC. +For all three kinds, key words in PHEPs must be interpreted according to [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119); the use of `must`, `must not`, `should`, and `should not` are preferred to the alternatives. + # PHEP Workflow ## PHEP Editors @@ -167,6 +169,8 @@ PHEPs should be restricted to the ASCII subset of UTF-8 where practicable. Examp The PHEP text files are automatically rendered by the GitHub interface for easier online reading. The Markdown source is the version of record. +The readability of the diff should be considered when editing a PHEP. + # PHEP Header Preamble Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) 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. From 55e41827f9dcc131eca4d95ac9d9791c4778ed5d Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 24 Oct 2023 10:13:39 -0400 Subject: [PATCH 09/84] phep-0001: all workflow is in GitHub; definitions of consensus --- pheps/phep-0001.md | 65 ++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index c7c07dc..a54f0c3 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -11,14 +11,14 @@ Post-History: # What is a PHEP? PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the PyHC community, or describing a new standard for Python or its processes or environment. The PHEP should provide a concise technical specification of the feature and a rationale for the feature. -We intend PHEPs to be the primary mechanisms for proposing major new standards, for collecting community input on an issue, and for documenting the design decisions that have gone into PyHC standards and recommendations. The PHEP author is responsible for building consensus within the community and documenting dissenting opinions. +We intend PHEPs to be the primary mechanisms for proposing major new standards, for collecting community input on an issue, and for documenting the design decisions that have gone into PyHC standards and recommendations. The purpose of the PHEP process is to develop and document consensus within the community. The PHEP author is responsible for building consensus and documenting dissenting opinions. Because the PHEPs 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. # PHEP Audience The typical primary audience for PHEPs are the developers of PyHC packages, as well as developers of other implementations of the Python language specification. -However, other parts of the PyHC community may also choose to use the process (particularly for Informational PHEPs) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects. +However, other parts of the PyHC community (hereafter "community") may also choose to use the process (particularly for Informational PHEPs) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects. # PHEP Types There are three kinds of PHEP: @@ -48,9 +48,9 @@ The editors can be contacted by mentioning `@heliophysicsPy/pep-editors` on GitH ## Start with an idea The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have a champion - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Posting to the PyHC mailing list or Element is usually the best way to go about this. +Each PHEP must have a champion - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Posting to the PyHC mailing list or Element/Slack is usually the best way to go about this. -Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. +Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. Once the champion has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft PHEP to make properly formatted, of high quality, and to address initial concerns about the proposal. @@ -62,7 +62,7 @@ The standard PHEP workflow is: * You, the PHEP author, fork the PHEP repository, and create a file named `phep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). * Update [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) such that any co-author(s) or sponsors with write access to the standards 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. +* Push this to a branch (not `main`) of your GitHub fork and submit a draft pull request. * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is 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. @@ -72,48 +72,47 @@ The standard PHEP workflow is: If the PHEP 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 PHEP a number. All PHEPs are sequentially-numbered at time of assignment. This includes meta-PHEPs. "Special" numbers (X, 0, etc.) are not used. - -Once the review process is complete, and the PHEP editors approve it (note that this is not the same as accepting your PHEP!), they will squash commit your pull request onto main. +* Once approved, they will assign your PHEP a number. All PHEPs are sequentially-numbered at time of assignment. This includes meta-PHEPs. "Special" numbers (X, 0, etc.) are not used. Upon approval, the PHEP PR must be marked ready for review. The PHEP editors will not unreasonably deny publication of a PHEP. Reasons for denying PHEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the PyHC philosophy. Standards Track PHEPs may consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation in an existing or new PyHC package be co-developed with the PHEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation. ## Discussing a PHEP -As soon as a PHEP number has been assigned and the draft PHEP is committed to the PHEP repository, a discussion thread for the PHEP should be created to provide a central place to discuss and review its contents, and the PHEP should be updated so that the `Discussions-To` header links to it. +As soon as the draft PHEP is submitted in an open PR and a PHEP number has been assigned, a discussion thread for the PHEP must be created to provide a central place to discuss and review its contents, and the PHEP must be updated so that the `Discussions-To` header links to it. The venue for this discussion must be the GitHub discussion thread for the PR with the draft PHEP. The discussion must also be announced by the PHEP authors via reasonable venues; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Element/Slack. -The PHEP authors (or sponsor, if applicable) may select any reasonable venue for the discussion, so long as the the following criteria are met: +Informal conversation may happen in the PyHC mailing list, Element/Slack, or private side channels. However, the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and any side conversations should ultimately result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the PHEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Approved". -* The forum is appropriate to the PHEP's topic. -* The thread is publicly available on the web so that all interested parties can participate. -* The discussion is subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). -* A direct link to the current discussion thread is provided in the PHEP under the `Discussions-To` header. +PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry added with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may certainly contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. Rebasing of history before a push for greater clarity is acceptable. -The PyHC mailing list is the preferred choice for most new PHEPs. +PHEP authors are also responsible for managing the progress of the discussion of their PHEP, for instance by updating the PR description to highlight topics of particular interest and to provide the dates of votes on the PHEP resolution. -If a PHEP 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 a PHEP undergoes a significant re-write or other major, substantive changes to its proposed specification, the author(s) and editor may discuss closing the existing PR and opening a new one, starting from the changed version. If this occurs, the `Discussions-To` link must be updated. PHEP authors are responsible for collecting community feedback on a PHEP 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 PHEP's subject matter, and picking an appropriately-specialized discussion for the PHEP's topic (if applicable) should be considered. PHEP authors should use their discretion here. -Once the PHEP is assigned a number and committed to the PHEP 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 PHEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the community will consider when reviewing the PHEP. +PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). ## PHEP Review & Resolution -Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community once the authors (and sponsor, if any) determine the PHEP is ready for final review and resolution. A PHEP is accepted when approved by consensus of attendees (virtual or in-person) at both a PyHC biweekly telecon and a biennial PyHC meeting with no edits to the PHEP occurring in between. Potential approval of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via email or Element chat, ensuring that the PHEP author is notified. +Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community once the authors determine the PHEP is ready for final review and resolution. A PHEP is accepted when approved by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential approval of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via email or Element/Slack chat, provided that they ensure the PHEP author is notified. + +A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. + +"Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make a compelling case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. For a PHEP 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 "pythonic" in order to be accepted by the community. (However, "pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) -Pronouncements of PHEP resolution will be posted to the PHEPs category on the Python Discourse. +Pronouncements of PHEP resolution will be posted to the PyHC mailing list. -Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final". +Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final" upon acceptance. If a PHEP requires additional design and interface feedback before committing to long term stability, it must remain in "Draft". Alternatively, its scope can be reduced (e.g. by deferring some features to later PHEPs). If no progress is being made on the PHEP, the editor should consult the author. The author may resume work on the PHEP, [transfer it to another author](transferring-phep-ownership), or withdraw it. If the author takes none of these actions, the editor may choose to bring the PHEP to the community for approval or rejection in its current form. -A PHEP can also be "Rejected" if it fails community approval and the author is not willing or able to modify it. 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 PHEP author themselves has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. +If a PHEP fails to find consensus, the author may choose to modify it for reconsideration in the future. The PHEP may also be "Withdrawn" if the PHEP author themselves has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also be "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. -When a PHEP changes state, the PHEP text must 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 PHEP. +When a PHEP changes state, the PHEP text must 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 minutes of the telecons and meetings making a decision on the PHEP. PHEPs can also be replaced by a different PHEP, rendering the original obsolete. @@ -123,6 +122,8 @@ The possible paths of the status of PHEPs are as follows: While not shown in the diagram, "Accepted" PHEPs 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 PHEP. +Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main`. + ## PHEP Maintenance PHEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected, Withdrawn, or Replaced state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. @@ -131,7 +132,9 @@ If changes based on implementation experience and user feedback are made to PHEP Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. -Changes to PHEPs in the Final state are limited to the preamble1, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. +Changes to PHEPs in the Final state are limited to the preamble, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. + +Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. # What belongs in a successful PHEP? Each PHEP should have the following parts/sections: @@ -222,15 +225,15 @@ PHEPs may include auxiliary files such as diagrams. Such files should be named ` Alternatively, all support files may be placed in a subdirectory called `phep-XXXX`, where "XXXX" is the PHEP number. When using a subdirectory, there are no constraints on the names used in files. # Changing Existing PHEPs -Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be first proposed on the PHEP's discussion thread listed in its `Discussions-To` header, while copyedits and corrections can be submitted as a GitHub issue or GitHub pull request. PHEP authors with write access to the PHEP repository can update the PHEPs themselves by using git push or a GitHub PR to submit their changes. For guidance on modifying other PHEPs, consult the PHEP Maintenance section. +Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be proposed on the PHEP's discussion thread listed in its `Discussions-To` header. For guidance on modifying other PHEPs, consult the PHEP Maintenance section. -See the Contributing Guide for additional details, and when in doubt, please check first with the PHEP author and/or a PHEP editor. +When in doubt, please check first with the PHEP author and/or a PHEP editor. # Transferring PHEP Ownership It occasionally becomes necessary to transfer ownership of PHEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, 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 PHEP 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that's not possible, an author can always submit a competing PHEP. -If you are interested in assuming ownership of a PHEP, you can also do this via pull request. Fork the `standards` repository, make your ownership modification, and submit a pull request. You should mention both the original author and `@heliophysicsPy/phep-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 PHEP editors will make a unilateral decision (it's not like such decisions can't be reversed :). +If you are interested in assuming ownership of a PHEP, you can also do this via the pull request discussion thread. Mention both the original author and `@heliophysicsPy/phep-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 PHEP editors will make a unilateral decision, which can be reversed. # PHEP Editor Responsibilities & Workflow @@ -249,14 +252,14 @@ For each new PHEP that comes in an editor does the following: If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. If Markdown formatting is a problem, ask the author(s) to resubmit. -Once the PHEP is ready for the repository, a PHEP editor will: +Once the PHEP is ready for discussion, a PHEP editor will: -* Assign a PHEP number (almost always just the next available number, but sometimes it's a special/joke number, like 666 or 3141). +* Assign a PHEP number (almost always just the next available number, generally avoiding special/joke numbers). * Check that the author has correctly labeled the PHEP's type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft". -* Merge the new (or updated) PHEP. -* Inform the author of the next steps (open a discussion thread and update the PHEP with it, post an announcement, etc). +* Mark the PR ready for review. +* Inform the author of the next steps (update the PHEP with the PR link, post an announcement, etc). -Updates to existing PHEPs should be submitted as a GitHub pull request. +Updates to existing PHEPs should be submitted as comments in the GitHub pull request. PHEP editors don't pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). They may participate in the community discussion of a PHEP but have no obligation to be advocates. From 929b570274f0881a9aaf2efb53286a35436b83ab Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 24 Oct 2023 10:33:46 -0400 Subject: [PATCH 10/84] phep-0001: define leadership --- pheps/phep-0001.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index a54f0c3..7e3ed45 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -16,10 +16,13 @@ We intend PHEPs to be the primary mechanisms for proposing major new standards, Because the PHEPs 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. # PHEP Audience + The typical primary audience for PHEPs are the developers of PyHC packages, as well as developers of other implementations of the Python language specification. However, other parts of the PyHC community (hereafter "community") may also choose to use the process (particularly for Informational PHEPs) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects. +This PHEP makes reference to "PyHC leadership": individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or other such group as appropriately designated in the future, such as a steering committee. + # PHEP Types There are three kinds of PHEP: @@ -41,7 +44,7 @@ For all three kinds, key words in PHEPs must be interpreted according to [RFC211 The PHEP editors are individuals responsible for managing the administrative and editorial aspects of the PHEP workflow (e.g. assigning PHEP numbers and changing their status). See [PHEP Editor Responsibilities & Workflow](#phep-editor-responsibilities-workflow) for details. -PHEP editorship is by nomination of the current editors, subject to approval of the individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or a steering committee or other such group as appropriately designated. In the event there are fewer than two active editors, such authority may appoint editors from active participants in the community, sufficient to bring the total to two. +PHEP editorship is by nomination of the current editors, subject to approval of PyHC leadership. In the event there are fewer than two active editors, PyHC leadership may appoint editors from active participants in the community, sufficient to bring the total to two. The editors can be contacted by mentioning `@heliophysicsPy/pep-editors` on GitHub. All of the PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. @@ -263,7 +266,7 @@ Updates to existing PHEPs should be submitted as comments in the GitHub pull req PHEP editors don't pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). They may participate in the community discussion of a PHEP but have no obligation to be advocates. -Disagreements with editors must be mediated by those with the authority to approve editors (as documented in [PHEP editors](#phep-editors)) and they may impose sanctions, up to and including removal of the editor role. +Disagreements with editors must be mediated by PyHC leadership (as documented in [PHEP audience](#phep-audience)) and they may impose sanctions, up to and including removal of the editor role. # PHEP 1 Approval From e005c01f146f4ea5f0b50f768d573582fdecc50f Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 24 Oct 2023 11:36:03 -0400 Subject: [PATCH 11/84] phep-0001: edits for smoothness / consistency --- pheps/phep-0001.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 7e3ed45..2f5ab48 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -9,26 +9,26 @@ Created: 20-Oct-2023 Post-History: # What is a PHEP? -PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the PyHC community, or describing a new standard for Python or its processes or environment. The PHEP should provide a concise technical specification of the feature and a rationale for the feature. +PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the Python in Heliophysics Community (PyHC), describing its processes, or describing a new standard for its packages. The PHEP should provide a concise technical specification of the feature or standard and a rationale. -We intend PHEPs to be the primary mechanisms for proposing major new standards, for collecting community input on an issue, and for documenting the design decisions that have gone into PyHC standards and recommendations. The purpose of the PHEP process is to develop and document consensus within the community. The PHEP author is responsible for building consensus and documenting dissenting opinions. +We intend PHEPs to be the primary mechanisms for proposing major new standards, for collecting community input on an issue, and for documenting the design decisions that have gone into PyHC standards and recommendations. The purpose of the PHEP process is to develop and document consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. Because the PHEPs 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. # PHEP Audience -The typical primary audience for PHEPs are the developers of PyHC packages, as well as developers of other implementations of the Python language specification. +The typical primary audience for PHEPs are the developers of PyHC packages. However, other parts of the PyHC community (hereafter "community") may also choose to use the process (particularly for Informational PHEPs) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects. -This PHEP makes reference to "PyHC leadership": individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or other such group as appropriately designated in the future, such as a steering committee. +This PHEP makes reference to "PyHC leadership": individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or other individuals or groups as appropriately designated in the future, such as a steering committee. # PHEP Types There are three kinds of PHEP: 1. A **Standards** Track PHEP describes a new standard for PyHC packages. -2. An **Informational** PHEP describes a PyHC design issue, or provides general guidelines or information to the PyHC community, but does not propose a new standard. Informational PHEPs do not necessarily represent a PyHC community consensus or recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. -3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to (or an event in) a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, 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 PyHC development or other Community activities. Any meta-PHEP is also considered a Process PHEP. +2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a new standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. +3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to (or an event in) a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, 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 PyHC development or other community activities. Any meta-PHEP is also considered a Process PHEP. # PHEP Applicability **Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally should do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for approval. Standards track PHEP compliance should be considered as a factor in evaluating current and potential PyHC packages. @@ -53,12 +53,12 @@ The PHEP process begins with a new idea for PyHC. It is highly recommended that Each PHEP must have a champion - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Posting to the PyHC mailing list or Element/Slack is usually the best way to go about this. -Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. +Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. -Once the champion has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft PHEP to make properly formatted, of high quality, and to address initial concerns about the proposal. +Once the champion has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft PHEP to make it properly formatted, of high quality, and to address initial concerns about the proposal. ## Submitting a PHEP -The proposal should be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors). +The proposal must be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors). The standard PHEP workflow is: @@ -69,7 +69,7 @@ The standard PHEP workflow is: * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is 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 PHEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid MD markup will not be approved; here "invalid" include Markdown which provides clearly unintended output (in the discretion of the editors). + * The PHEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid Markdown (MD) markup will not be approved; here "invalid" include Markdown which provides clearly unintended output (in the discretion of the editors). Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. **Note**: Approval of the PHEP is no guarantee that there are no embarrassing mistakes! Correctness is the responsibility of authors and reviewers, not the editors. @@ -84,7 +84,7 @@ Standards Track PHEPs may consist of two parts, a design document and a referenc ## Discussing a PHEP As soon as the draft PHEP is submitted in an open PR and a PHEP number has been assigned, a discussion thread for the PHEP must be created to provide a central place to discuss and review its contents, and the PHEP must be updated so that the `Discussions-To` header links to it. The venue for this discussion must be the GitHub discussion thread for the PR with the draft PHEP. The discussion must also be announced by the PHEP authors via reasonable venues; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Element/Slack. -Informal conversation may happen in the PyHC mailing list, Element/Slack, or private side channels. However, the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and any side conversations should ultimately result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the PHEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Approved". +Informal conversation may happen in the PyHC mailing list, Element/Slack, or private side channels. However, the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and any side conversations should ultimately result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the PHEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry added with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may certainly contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. Rebasing of history before a push for greater clarity is acceptable. @@ -103,9 +103,9 @@ A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized "Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make a compelling case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. -For a PHEP 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 "pythonic" in order to be accepted by the community. (However, "pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) +For a PHEP 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 PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. (However, "pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) -Pronouncements of PHEP resolution will be posted to the PyHC mailing list. +The editors must post oronouncements of PHEP resolution to the PyHC mailing list. Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final" upon acceptance. @@ -113,11 +113,11 @@ If a PHEP requires additional design and interface feedback before committing to If no progress is being made on the PHEP, the editor should consult the author. The author may resume work on the PHEP, [transfer it to another author](transferring-phep-ownership), or withdraw it. If the author takes none of these actions, the editor may choose to bring the PHEP to the community for approval or rejection in its current form. -If a PHEP fails to find consensus, the author may choose to modify it for reconsideration in the future. The PHEP may also be "Withdrawn" if the PHEP author themselves has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also be "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. +If a PHEP fails to find consensus, the author may choose to modify it for reconsideration in the future. The PHEP may also be "Withdrawn" if the PHEP author themself has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also be "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. -When a PHEP changes state, the PHEP text must 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 minutes of the telecons and meetings making a decision on the PHEP. +When a PHEP changes state, the PHEP text must 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 minutes of the telecons and meetings where a decision on the PHEP was made. -PHEPs can also be replaced by a different PHEP, rendering the original obsolete. +Final PHEPs can also be replaced by a different PHEP, rendering the original obsolete. The possible paths of the status of PHEPs are as follows: @@ -144,7 +144,7 @@ Each PHEP should have the following parts/sections: 1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing meta-data about the PHEP, including the PHEP 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 PHEPs that want to change the PyHC or ecosystem. It should clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP submissions without sufficient motivation may be rejected. +3. Motivation - The motivation is critical for PHEPs that want to change the PyHC ecosystem. It should clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. @@ -171,7 +171,7 @@ Each PHEP should have the following parts/sections: # PHEP Formats and Templates PHEPs are UTF-8 encoded text files using the Markdown format. Markdown allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). -PHEPs should be restricted to the ASCII subset of UTF-8 where practicable. Examples of cases where it is not practicable include the inclusion of personal names. +PHEPs should be restricted to the ASCII subset of UTF-8 where practicable. Examples of cases where it is not practicable include personal names. The PHEP text files are automatically rendered by the GitHub interface for easier online reading. The Markdown source is the version of record. @@ -194,7 +194,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Post-History: * Replaces: - * Superseded-By: + * Replaced-By: * Resolution: The Author header lists the names, and optionally the email addresses of all the authors/owners of the PHEP. The format of the Author header values must be: @@ -217,18 +217,18 @@ The optional Topic header lists the special topic, if any, the PHEP belongs unde The format of a PHEP is specified with a Content-Type header. All PHEPs must use Markdown, and have a value of `text/markdown; charset=UTF-8; variant=CommonMark`. -The Created header records the date that the PHEP was assigned a number, while Post-History is used to record the dates of and corresponding URLs to the Discussions-To threads for the PHEP, 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`. +The Created header records the date that the PHEP was assigned a number, while Post-History is used to record the dates of pushes to the pull request for the PHEP, with the former as the linked text. Both sets of dates should be in `dd-mmm-yyyy` format, e.g. `14-Aug-2001`. PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP depends on. -PHEPs may also have a Superseded-By header indicating that a PHEP has been rendered obsolete by a later document; the value is the number of the PHEP that replaces the current document. The newer PHEP must have a Replaces header containing the number of the PHEP that it rendered obsolete. +PHEPs may also have a Replaced-By header indicating that a PHEP has been rendered obsolete by a later document; the value is the number of the PHEP that replaces the current document. The newer PHEP must have a Replaces header containing the number of the PHEP that it rendered obsolete. # Auxiliary Files PHEPs may include auxiliary files such as diagrams. Such files should be named `phep-XXXX-Y.ext`, where "XXXX" is the PHEP 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 `phep-XXXX`, where "XXXX" is the PHEP number. When using a subdirectory, there are no constraints on the names used in files. # Changing Existing PHEPs -Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be proposed on the PHEP's discussion thread listed in its `Discussions-To` header. For guidance on modifying other PHEPs, consult the PHEP Maintenance section. +Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be proposed on the PHEP's discussion thread listed in its `Discussions-To` header. For guidance on modifying other PHEPs, consult the [PHEP Maintenance](#phep-maintenance) section. When in doubt, please check first with the PHEP author and/or a PHEP editor. @@ -266,7 +266,7 @@ Updates to existing PHEPs should be submitted as comments in the GitHub pull req PHEP editors don't pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). They may participate in the community discussion of a PHEP but have no obligation to be advocates. -Disagreements with editors must be mediated by PyHC leadership (as documented in [PHEP audience](#phep-audience)) and they may impose sanctions, up to and including removal of the editor role. +Disagreements with editors must be mediated by PyHC leadership (as documented in [PHEP audience](#phep-audience)) and they may impose sanctions, including removal of the editor role. # PHEP 1 Approval From acac85dfc28c3456b7f9a33f2a810380246aa645 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 24 Oct 2023 11:46:19 -0400 Subject: [PATCH 12/84] phep-0001: motivation and posting date --- pheps/phep-0001.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 2f5ab48..df5111a 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -6,7 +6,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: +Post-History: 24-Oct-2023 # What is a PHEP? PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the Python in Heliophysics Community (PyHC), describing its processes, or describing a new standard for its packages. The PHEP should provide a concise technical specification of the feature or standard and a rationale. @@ -15,6 +15,11 @@ We intend PHEPs to be the primary mechanisms for proposing major new standards, Because the PHEPs 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. +# PHEP Motivation +The [PyHC standards](https://doi.org/10.5281/zenodo.2529131) have not been updated since their initial approval in 2018, and indeed there is no established process for updating them. PyHC discussions often involve what packages "should" do, or "should be required" to do. For standards to be effective, they need to be seen as legitimate by those they may be imposed on. + +A mechanism is needed to capture the sense of the community and allow it to progress while recognizing that the community is broad, diffuse, and diverse, and not all stakeholders are able to be present for all conversations. + # PHEP Audience The typical primary audience for PHEPs are the developers of PyHC packages. From 6a45ccdab61ea56e189003807722413fb78dc3a7 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 24 Oct 2023 12:02:01 -0400 Subject: [PATCH 13/84] phep-0001: put in PR link --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index df5111a..352ddd0 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -1,7 +1,7 @@ PHEP: 1 Title: PHEP Purpose and Guidelines Author: Jonathan Niehof -Discussions-To: +Discussions-To: https://github.com/heliophysicsPy/standards/pull/22 Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark From 13992906f5c85453cf20362472fe58fb00c90324 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 24 Oct 2023 12:32:22 -0400 Subject: [PATCH 14/84] phep-0001: typos and small wording changes from initial reviews --- pheps/phep-0001.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 352ddd0..39fea05 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -22,7 +22,7 @@ A mechanism is needed to capture the sense of the community and allow it to prog # PHEP Audience -The typical primary audience for PHEPs are the developers of PyHC packages. +The typical primary audience for PHEPs are the developers and user communities of PyHC packages. However, other parts of the PyHC community (hereafter "community") may also choose to use the process (particularly for Informational PHEPs) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects. @@ -31,7 +31,7 @@ This PHEP makes reference to "PyHC leadership": individuals or groups with statu # PHEP Types There are three kinds of PHEP: -1. A **Standards** Track PHEP describes a new standard for PyHC packages. +1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. 2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a new standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. 3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to (or an event in) a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, 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 PyHC development or other community activities. Any meta-PHEP is also considered a Process PHEP. @@ -110,7 +110,7 @@ A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized For a PHEP 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 PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. (However, "pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) -The editors must post oronouncements of PHEP resolution to the PyHC mailing list. +The editors must post announcements of PHEP resolution to the PyHC mailing list. Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final" upon acceptance. From 5ade2425600eeae088866c0be4aef4994838851b Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 30 Oct 2023 10:23:09 -0400 Subject: [PATCH 15/84] phep-0001: codefence preamble --- pheps/phep-0001.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 39fea05..0e016ca 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -1,3 +1,4 @@ +``` PHEP: 1 Title: PHEP Purpose and Guidelines Author: Jonathan Niehof @@ -7,6 +8,7 @@ Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 Post-History: 24-Oct-2023 +``` # What is a PHEP? PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the Python in Heliophysics Community (PyHC), describing its processes, or describing a new standard for its packages. The PHEP should provide a concise technical specification of the feature or standard and a rationale. @@ -184,8 +186,9 @@ The readability of the diff should be considered when editing a PHEP. # PHEP Header Preamble -Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) 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. +Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style header preamble, marked off with a [code fence](https://spec.commonmark.org/current/#fenced-code-blocks). The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required. + ``` PHEP: Title: Author: @@ -201,6 +204,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf * Replaces: * Replaced-By: * Resolution: + ``` The Author header lists the names, and optionally the email addresses of all the authors/owners of the PHEP. The format of the Author header values must be: From 744ff1e120d1953b0ae8e5868d3e982cbe9635dc Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 30 Oct 2023 10:40:01 -0400 Subject: [PATCH 16/84] phep-0001: venues for initial discussion include GH issue --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 0e016ca..d3ba57a 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -58,7 +58,7 @@ The editors can be contacted by mentioning `@heliophysicsPy/pep-editors` on GitH ## Start with an idea The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have a champion - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Posting to the PyHC mailing list or Element/Slack is usually the best way to go about this. +Each PHEP must have a champion - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include discussion on a PyHC telecon, posting to the PyHC mailing list, asking on PyHC Element/Slack, and [opening an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should then be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic and this information discussion may happen in multiple places. Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. From 98909f0eccb49e47f0830fdd5bef8ebad1e7018a Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 30 Oct 2023 10:42:06 -0400 Subject: [PATCH 17/84] phep-0001: minor wording change on format-at-submission --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index d3ba57a..4e8b7b4 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -65,7 +65,7 @@ Vetting an idea publicly before going as far as writing a PHEP is meant to save Once the champion has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft PHEP to make it properly formatted, of high quality, and to address initial concerns about the proposal. ## Submitting a PHEP -The proposal must be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors). +The proposal must be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below before it can be accepted. The editors may correct minor errors. The standard PHEP workflow is: From 28d31b8922ad72a9e3c1789eeaf8574131240cb5 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 30 Oct 2023 11:15:51 -0400 Subject: [PATCH 18/84] phep-0001: fiddly bits on encoding and styles --- pheps/phep-0001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 4e8b7b4..52080a3 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -178,12 +178,12 @@ Each PHEP should have the following parts/sections: # PHEP Formats and Templates PHEPs are UTF-8 encoded text files using the Markdown format. Markdown allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). -PHEPs should be restricted to the ASCII subset of UTF-8 where practicable. Examples of cases where it is not practicable include personal names. - The PHEP text files are automatically rendered by the GitHub interface for easier online reading. The Markdown source is the version of record. The readability of the diff should be considered when editing a PHEP. +The editors are responsible for enforcing PHEP format and consistency of style within a PHEP. They may use automated tools (e.g. pre-commit hooks) to assist. + # PHEP Header Preamble Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style header preamble, marked off with a [code fence](https://spec.commonmark.org/current/#fenced-code-blocks). The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required. From 21ebaf4bd33bfbbbc0f6b1157d612b8acac6bcc8 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 30 Oct 2023 11:27:37 -0400 Subject: [PATCH 19/84] phep-0001: spell metadata, remove length limit on title --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 52080a3..5372ccb 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -149,7 +149,7 @@ Preamble changes are made via PR to the `standards` repository, merged by PHEP e # What belongs in a successful PHEP? Each PHEP should have the following parts/sections: -1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing meta-data about the PHEP, including the PHEP number, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc. +1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, including the PHEP number, a short descriptive title, 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 PHEPs that want to change the PyHC ecosystem. It should clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. From 83e5453b6d6e6160f27da39c12f0d2b0b566ddf5 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 30 Oct 2023 11:34:29 -0400 Subject: [PATCH 20/84] phep-0001: typos and such --- pheps/phep-0001.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 5372ccb..ca2f592 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -53,7 +53,7 @@ The PHEP editors are individuals responsible for managing the administrative and PHEP editorship is by nomination of the current editors, subject to approval of PyHC leadership. In the event there are fewer than two active editors, PyHC leadership may appoint editors from active participants in the community, sufficient to bring the total to two. -The editors can be contacted by mentioning `@heliophysicsPy/pep-editors` on GitHub. All of the PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. +The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on GitHub. All of the PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. ## Start with an idea The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. @@ -197,16 +197,16 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Withdrawn | Final | Superseded> Type: Content-Type: text/markdown; charset=UTF-8; variant=CommonMark - * Requires: + * Requires: Created: Post-History: - * Replaces: - * Replaced-By: + * Replaces: + * Replaced-By: * Resolution: ``` -The Author header lists the names, and optionally the email addresses of all the authors/owners of the PHEP. The format of the Author header values must be: +The Author header lists the names and optionally the email addresses of all the authors/owners of the PHEP. The format of the Author header values must be: `Random J. User ` @@ -249,11 +249,11 @@ If you are interested in assuming ownership of a PHEP, you can also do this via # PHEP Editor Responsibilities & Workflow -A PHEP editor must be added to the `@heliophysicsPy/pep-editors` group on GitHub and must watch the `standards` repository. +A PHEP editor must be added to the `@heliophysicsPy/phep-editors` group on GitHub and must watch the `standards` repository. Other community members with write access to the `standards` repository may handle the tasks that would normally be taken care of by the PHEP editors. Alternately, even those with write access may request assistance from PHEP editors by mentioning `@heliophysicsPy/phep-editors` on GitHub. -For each new PHEP that comes in an editor does the following: +For each new PHEP that comes in, an editor does the following: * Read the PHEP 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. @@ -269,7 +269,7 @@ Once the PHEP is ready for discussion, a PHEP editor will: * Assign a PHEP number (almost always just the next available number, generally avoiding special/joke numbers). * Check that the author has correctly labeled the PHEP's type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft". * Mark the PR ready for review. -* Inform the author of the next steps (update the PHEP with the PR link, post an announcement, etc). +* Inform the author of the next steps (update the PHEP with the PR link, post an announcement, etc.). Updates to existing PHEPs should be submitted as comments in the GitHub pull request. From f8fc717c472da64c6793994c7d15e0c51ebc2a8a Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 30 Oct 2023 11:36:14 -0400 Subject: [PATCH 21/84] phep-0001: clarify editor role --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index ca2f592..f12a991 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -273,7 +273,7 @@ Once the PHEP is ready for discussion, a PHEP editor will: Updates to existing PHEPs should be submitted as comments in the GitHub pull request. -PHEP editors don't pass judgment on PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). They may participate in the community discussion of a PHEP but have no obligation to be advocates. +PHEP editors do not make judgments on the content or merits of PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). They may participate in the community discussion of a PHEP but have no obligation to be advocates. Disagreements with editors must be mediated by PyHC leadership (as documented in [PHEP audience](#phep-audience)) and they may impose sanctions, including removal of the editor role. From afdae4b12d667ff63a54d23b87a4e6a96b9b6771 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 31 Oct 2023 09:10:58 -0400 Subject: [PATCH 22/84] phep-0001: tighten up and clarify (esp. distinguish 'accept' and 'approve') --- pheps/phep-0001.md | 122 ++++++++++++++++++++------------------------- 1 file changed, 55 insertions(+), 67 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index f12a991..a07908b 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -11,34 +11,34 @@ Post-History: 24-Oct-2023 ``` # What is a PHEP? -PHEP stands for PyHC Enhancement Proposal. A PHEP is a design document providing information to the Python in Heliophysics Community (PyHC), describing its processes, or describing a new standard for its packages. The PHEP should provide a concise technical specification of the feature or standard and a rationale. +PHEP stands for PyHC Enhancement Proposal. A PHEP provides information to the Python in Heliophysics Community (PyHC), describes its processes, or establishes standards for its packages. The PHEP should provide a concise technical specification of the feature or standard and a rationale. -We intend PHEPs to be the primary mechanisms for proposing major new standards, for collecting community input on an issue, and for documenting the design decisions that have gone into PyHC standards and recommendations. The purpose of the PHEP process is to develop and document consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. +PHEPs are the primary mechanism for proposing standards, for collecting community input, and for documenting the design decisions underlying PyHC standards and recommendations. The PHEP process develops and documents consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. -Because the PHEPs 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. +Because PHEPs 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. # PHEP Motivation -The [PyHC standards](https://doi.org/10.5281/zenodo.2529131) have not been updated since their initial approval in 2018, and indeed there is no established process for updating them. PyHC discussions often involve what packages "should" do, or "should be required" to do. For standards to be effective, they need to be seen as legitimate by those they may be imposed on. +The [PyHC standards](https://doi.org/10.5281/zenodo.2529131) have not been updated since their initial approval in 2018, and there is no established process for updating them. PyHC discussions often involve what packages "should" do, or "should be required" to do. For standards to be effective, they need to be seen as legitimate by those they may be imposed on. -A mechanism is needed to capture the sense of the community and allow it to progress while recognizing that the community is broad, diffuse, and diverse, and not all stakeholders are able to be present for all conversations. +A mechanism is needed to capture the sense of the community and allow it to progress while recognizing that the community is broad, diffuse, and diverse, and not all stakeholders are present for all conversations. # PHEP Audience -The typical primary audience for PHEPs are the developers and user communities of PyHC packages. +The typical audience for PHEPs is the developers and user communities of PyHC packages. -However, other parts of the PyHC community (hereafter "community") may also choose to use the process (particularly for Informational PHEPs) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects. +However, other parts of the PyHC community (hereafter "community") may also use the process (particularly for Informational PHEPs) to document conventions and to manage complex design coordination problems that require collaboration across multiple projects. -This PHEP makes reference to "PyHC leadership": individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or other individuals or groups as appropriately designated in the future, such as a steering committee. +This PHEP refers to "PyHC leadership": individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or other individuals or groups appropriately designated in the future, such as a steering committee. # PHEP Types There are three kinds of PHEP: 1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. 2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a new standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. -3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to (or an event in) a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, 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 PyHC development or other community activities. Any meta-PHEP is also considered a Process PHEP. +3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. Any meta-PHEP is also considered a Process PHEP. # PHEP Applicability -**Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally should do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for approval. Standards track PHEP compliance should be considered as a factor in evaluating current and potential PyHC packages. +**Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally should do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for acceptance. Standards track PHEP compliance should be considered as a factor in evaluating current and potential PyHC packages. **Informational** PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. @@ -49,27 +49,29 @@ For all three kinds, key words in PHEPs must be interpreted according to [RFC211 # PHEP Workflow ## PHEP Editors -The PHEP editors are individuals responsible for managing the administrative and editorial aspects of the PHEP workflow (e.g. assigning PHEP numbers and changing their status). See [PHEP Editor Responsibilities & Workflow](#phep-editor-responsibilities-workflow) for details. +PHEP editors are responsible for managing the administrative and editorial aspects of the PHEP workflow (e.g. assigning PHEP numbers and changing their status). See [PHEP Editor Responsibilities & Workflow](#phep-editor-responsibilities-workflow) for details. -PHEP editorship is by nomination of the current editors, subject to approval of PyHC leadership. In the event there are fewer than two active editors, PyHC leadership may appoint editors from active participants in the community, sufficient to bring the total to two. +PHEP editorship is by nomination of the current editors, subject to approval by PyHC leadership. In the event there are fewer than two active editors, PyHC leadership may appoint editors from active participants in the community, sufficient to bring the total to two. -The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on GitHub. All of the PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. +The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on GitHub. All PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. ## Start with an idea The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have a champion - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include discussion on a PyHC telecon, posting to the PyHC mailing list, asking on PyHC Element/Slack, and [opening an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should then be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic and this information discussion may happen in multiple places. +Each PHEP must have an author - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include discussion on a PyHC telecon, posting to the PyHC mailing list, asking on PyHC Element/Slack, and [opening an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should then be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic and this informal discussion may happen in multiple places. -Vetting an idea publicly before going as far as writing a PHEP is meant to save the potential author time. Asking the 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. +Vetting an idea publicly before writing a PHEP is meant to save the author time. Asking the community first if an idea is original helps prevent too much time being spent on something that may 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. Just because an idea sounds good to the author does not mean it will work for most people in most areas. -Once the champion has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft PHEP to make it properly formatted, of high quality, and to address initial concerns about the proposal. +Early vetting allows PHEP authors to collecting community feedback while avoiding 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 PHEP's subject matter, and picking an appropriately-specialized discussion for the PHEP's topic (if applicable) should be considered. + +Once the author has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be submitted as described below. This gives the author a chance to flesh out the draft PHEP to make it properly formatted, of high quality, and to address initial concerns about the proposal. ## Submitting a PHEP -The proposal must be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below before it can be accepted. The editors may correct minor errors. +The proposal must be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below. The editors may correct minor errors. The standard PHEP workflow is: -* You, the PHEP author, fork the PHEP repository, and create a file named `phep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP number. +* You, the PHEP author, fork the PyHC [standards](https://github.com/heliophysicsPy/standards) repository, and create a file named `phep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). * Update [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) such that any co-author(s) or sponsors with write access to the standards repository are listed for your new file. This ensures any future pull requests changing the file will be assigned to them. * Push this to a branch (not `main`) of your GitHub fork and submit a draft pull request. @@ -78,39 +80,37 @@ The standard PHEP workflow is: * The title accurately describes the content. * The PHEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid Markdown (MD) markup will not be approved; here "invalid" include Markdown which provides clearly unintended output (in the discretion of the editors). - Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. **Note**: Approval of the PHEP is no guarantee that there are no embarrassing mistakes! Correctness is the responsibility of authors and reviewers, not the editors. + Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. Correctness is the responsibility of authors and reviewers, not the editors. - If the PHEP isn't ready for approval, an editor will send it back to the author for revision, with specific instructions. + If the PHEP isn't ready for approval, an editor will send it back to the author with specific instructions. -* Once approved, they will assign your PHEP a number. All PHEPs are sequentially-numbered at time of assignment. This includes meta-PHEPs. "Special" numbers (X, 0, etc.) are not used. Upon approval, the PHEP PR must be marked ready for review. +* Once approved, they will assign your PHEP a number. All PHEPs are sequentially-numbered at time of assignment. This includes meta-PHEPs. "Special" numbers (X, 0, etc.) are not used. Upon approval, the author must mark the PHEP PR ready for review. -The PHEP editors will not unreasonably deny publication of a PHEP. Reasons for denying PHEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the PyHC philosophy. +The PHEP editors will not unreasonably deny approval of a PHEP. Reasons for denying PHEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the PyHC philosophy. -Standards Track PHEPs may consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation in an existing or new PyHC package be co-developed with the PHEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation. +Standards Track PHEPs may consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation in an existing or new PyHC package be co-developed with the PHEP, as ideas that sound good in principle sometimes turn out to be impractical when implemented. ## Discussing a PHEP -As soon as the draft PHEP is submitted in an open PR and a PHEP number has been assigned, a discussion thread for the PHEP must be created to provide a central place to discuss and review its contents, and the PHEP must be updated so that the `Discussions-To` header links to it. The venue for this discussion must be the GitHub discussion thread for the PR with the draft PHEP. The discussion must also be announced by the PHEP authors via reasonable venues; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Element/Slack. - -Informal conversation may happen in the PyHC mailing list, Element/Slack, or private side channels. However, the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and any side conversations should ultimately result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the PHEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". +Once the draft PHEP is submitted in an open PR and a PHEP number has been assigned, the PR discussion thread provides the central place to discuss and review its contents. The PHEP must be updated so that the `Discussions-To` header links to the PR. The discussion must also be announced by the PHEP authors via reasonable means; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Element/Slack. -PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry added with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may certainly contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. Rebasing of history before a push for greater clarity is acceptable. +Informal conversation may happen in the PyHC mailing list, Element/Slack, or private side channels. However, the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and any side conversations should ultimately result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the PHEP review process. Feedback on this designated thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". -PHEP authors are also responsible for managing the progress of the discussion of their PHEP, for instance by updating the PR description to highlight topics of particular interest and to provide the dates of votes on the PHEP resolution. +PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. Rebasing of history before a push for greater clarity is acceptable. -If a PHEP undergoes a significant re-write or other major, substantive changes to its proposed specification, the author(s) and editor may discuss closing the existing PR and opening a new one, starting from the changed version. If this occurs, the `Discussions-To` link must be updated. +PHEP authors are responsible for managing the progress of the discussion of their PHEP, for instance by updating the PR description to highlight topics of particular interest and to provide the dates of votes on the PHEP resolution. -PHEP authors are responsible for collecting community feedback on a PHEP 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 PHEP's subject matter, and picking an appropriately-specialized discussion for the PHEP's topic (if applicable) should be considered. PHEP authors should use their discretion here. +If a PHEP undergoes a significant re-write or other major changes, the author(s) and editor may discuss closing the existing PR and opening a new one, starting from the changed version. If this occurs, the `Discussions-To` link must be updated. PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). ## PHEP Review & Resolution -Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community once the authors determine the PHEP is ready for final review and resolution. A PHEP is accepted when approved by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential approval of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via email or Element/Slack chat, provided that they ensure the PHEP author is notified. +Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community. A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via email or Element/Slack chat, provided that they ensure the PHEP author is notified. A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. "Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make a compelling case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. -For a PHEP 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 PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. (However, "pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) +For a PHEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed change. The change must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. ("Pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) The editors must post announcements of PHEP resolution to the PyHC mailing list. @@ -118,11 +118,11 @@ Once a PHEP has been accepted, the reference implementation, if applicable, must If a PHEP requires additional design and interface feedback before committing to long term stability, it must remain in "Draft". Alternatively, its scope can be reduced (e.g. by deferring some features to later PHEPs). -If no progress is being made on the PHEP, the editor should consult the author. The author may resume work on the PHEP, [transfer it to another author](transferring-phep-ownership), or withdraw it. If the author takes none of these actions, the editor may choose to bring the PHEP to the community for approval or rejection in its current form. +If no progress is being made on the PHEP, the editor should consult the author. The author may resume work on the PHEP, [transfer it to another author](transferring-phep-ownership), or withdraw it. If the author takes none of these actions, the editor may choose to bring the PHEP to the community for acceptance or rejection in its current form. -If a PHEP fails to find consensus, the author may choose to modify it for reconsideration in the future. The PHEP may also be "Withdrawn" if the PHEP author themself has decided that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also be "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. +If a PHEP fails to find consensus, the author may choose to modify it for reconsideration in the future. The PHEP may also be "Withdrawn" if the PHEP author themself decides that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also be "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. -When a PHEP changes state, the PHEP text must 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 minutes of the telecons and meetings where a decision on the PHEP was made. +When a PHEP changes state, the PHEP preamble must be updated accordingly. In addition to updating the Status field, the Resolution header must be added with a direct link to the minutes of the telecons and meetings where a decision on the PHEP was made. Final PHEPs can also be replaced by a different PHEP, rendering the original obsolete. @@ -147,27 +147,25 @@ Changes to PHEPs in the Final state are limited to the preamble, and only in the Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. # What belongs in a successful PHEP? -Each PHEP should have the following parts/sections: +Each PHEP should have the following elements, where they are applicable. It is suggested, but not required, that each element be addressed in a dedicated section of the PHEP. -1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, including the PHEP number, a short descriptive title, 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 PHEPs that want to change the PyHC ecosystem. It should clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. +1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, described [below](#phep-header-preamble). +2. Abstract - a short (~200 word) description of the issue being addressed. +3. Motivation - The motivation must clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. 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 standard. The specification should be detailed enough to allow competing, interoperable implementations. -6. Backwards Compatibility - All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. PHEP submissions without a sufficient backwards compatibility treatise may be rejected outright. -7. Security Implications - If there are security concerns in relation to the PHEP, those concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. -8. How to Teach This - For a PHEP that adds new functionality or changes behavior, it is helpful to include a section on how to teach users, new and experienced, how to apply the PHEP 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. +5. Specification - The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. +6. Backwards Compatibility - All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. +7. Security Implications - Any security concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. +8. How to Teach This - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work. 9. Reference Implementation - The reference implementation must be completed before any PHEP is given status "Final", but it need not be completed before the PHEP 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 the relevant PyHC project(s). -10. Rejected Ideas - Throughout the discussion of a PHEP, 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 PHEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions. +10. Rejected Ideas - Throughout the discussion of a PHEP, various ideas will be proposed which are not incorporated. 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 PHEP 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. @@ -176,7 +174,7 @@ Each PHEP should have the following parts/sections: 13. Copyright/license - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). # PHEP Formats and Templates -PHEPs are UTF-8 encoded text files using the Markdown format. Markdown allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). +PHEPs are UTF-8 encoded text files using the Markdown format. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). The PHEP text files are automatically rendered by the GitHub interface for easier online reading. The Markdown source is the version of record. @@ -218,12 +216,10 @@ if the address is not given. If there are multiple authors, each should be on a separate line following [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions. Note that personal email addresses in PHEPs will be obscured as a defense against spam harvesters. -The Discussions-To header provides the URL to the current canonical discussion thread for the PHEP. 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 Discussions-To header provides the URL to the current PR discussion thread for the PHEP. The Type header specifies the type of PHEP: Standards Track, Informational, or Process. -The optional Topic header lists the special topic, if any, the PHEP belongs under. See the Topic Index for the existing topics. - The format of a PHEP is specified with a Content-Type header. All PHEPs must use Markdown, and have a value of `text/markdown; charset=UTF-8; variant=CommonMark`. The Created header records the date that the PHEP was assigned a number, while Post-History is used to record the dates of pushes to the pull request for the PHEP, with the former as the linked text. Both sets of dates should be in `dd-mmm-yyyy` format, e.g. `14-Aug-2001`. @@ -236,16 +232,11 @@ PHEPs may also have a Replaced-By header indicating that a PHEP has been rendere PHEPs may include auxiliary files such as diagrams. Such files should be named `phep-XXXX-Y.ext`, where "XXXX" is the PHEP 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 `phep-XXXX`, where "XXXX" is the PHEP number. When using a subdirectory, there are no constraints on the names used in files. -# Changing Existing PHEPs -Draft PHEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted for review and resolution. Substantive content changes should generally be proposed on the PHEP's discussion thread listed in its `Discussions-To` header. For guidance on modifying other PHEPs, consult the [PHEP Maintenance](#phep-maintenance) section. - -When in doubt, please check first with the PHEP author and/or a PHEP editor. - # Transferring PHEP Ownership -It occasionally becomes necessary to transfer ownership of PHEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, 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 PHEP 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that's not possible, an author can always submit a competing PHEP. +It occasionally becomes necessary to transfer ownership of PHEPs to a new author. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, at their discretion. 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 PHEP process, or 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that's not possible, an author can always submit a competing PHEP. -If you are interested in assuming ownership of a PHEP, you can also do this via the pull request discussion thread. Mention both the original author and `@heliophysicsPy/phep-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 PHEP editors will make a unilateral decision, which can be reversed. +If you are interested in assuming ownership of a PHEP, you can do this via the pull request discussion thread. Mention both the original author and `@heliophysicsPy/phep-editors` in a comment on the pull request. If the original author doesn't respond in a timely manner, the PHEP editors will make a unilateral decision, which can be reversed. # PHEP Editor Responsibilities & Workflow @@ -262,24 +253,21 @@ For each new PHEP that comes in, an editor does the following: * Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.). Editors may correct problems themselves, but are not required to do so. * If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. This is to avoid a PHEP accidentally portraying a project as supporting a PHEP when in fact the support is based on conjecture. -If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. If Markdown formatting is a problem, ask the author(s) to resubmit. +If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. Once the PHEP is ready for discussion, a PHEP editor will: -* Assign a PHEP number (almost always just the next available number, generally avoiding special/joke numbers). +* Assign a PHEP number (almost always just the next available number). * Check that the author has correctly labeled the PHEP's type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft". -* Mark the PR ready for review. -* Inform the author of the next steps (update the PHEP with the PR link, post an announcement, etc.). - -Updates to existing PHEPs should be submitted as comments in the GitHub pull request. +* Ask the author to update the PHEP with the PR link, mark the PR ready for review, and post an announcement. -PHEP editors do not make judgments on the content or merits of PHEPs. They merely do the administrative & editorial part (which is generally a low volume task). They may participate in the community discussion of a PHEP but have no obligation to be advocates. +PHEP editors do not make judgments on the content or merits of PHEPs. They merely do the administrative & editorial part. They may participate in the community discussion of a PHEP but have no obligation to be advocates. Disagreements with editors must be mediated by PyHC leadership (as documented in [PHEP audience](#phep-audience)) and they may impose sanctions, including removal of the editor role. -# PHEP 1 Approval +# PHEP 1 Acceptance -This PHEP is subject to the same review and approval process that it proposes. +This PHEP is subject to the same review and acceptance process that it proposes. # Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. From f6fde3008ec6e0c8e1a0e6ee41e19a5d74af9513 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 31 Oct 2023 09:15:34 -0400 Subject: [PATCH 23/84] phep-0001: put more workflow in GitHub, remove CODEOWNERS messing around --- pheps/phep-0001.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index a07908b..84aa95e 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -73,7 +73,6 @@ The standard PHEP workflow is: * You, the PHEP author, fork the PyHC [standards](https://github.com/heliophysicsPy/standards) repository, and create a file named `phep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). -* Update [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) such that any co-author(s) or sponsors with write access to the standards repository are listed for your new file. This ensures any future pull requests changing the file will be assigned to them. * Push this to a branch (not `main`) of your GitHub fork and submit a draft pull request. * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. @@ -104,7 +103,7 @@ If a PHEP undergoes a significant re-write or other major changes, the author(s) PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). ## PHEP Review & Resolution -Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community. A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via email or Element/Slack chat, provided that they ensure the PHEP author is notified. +Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community. A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via comment on the PR. A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. @@ -242,14 +241,11 @@ If you are interested in assuming ownership of a PHEP, you can do this via the p A PHEP editor must be added to the `@heliophysicsPy/phep-editors` group on GitHub and must watch the `standards` repository. -Other community members with write access to the `standards` repository may handle the tasks that would normally be taken care of by the PHEP editors. Alternately, even those with write access may request assistance from PHEP editors by mentioning `@heliophysicsPy/phep-editors` on GitHub. - For each new PHEP that comes in, an editor does the following: * Read the PHEP 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. `.md`). -* Ensure that everyone listed as a co-author of the PHEP who has write access to the PHEP repository is added to [.github/CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). * Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.). Editors may correct problems themselves, but are not required to do so. * If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. This is to avoid a PHEP accidentally portraying a project as supporting a PHEP when in fact the support is based on conjecture. From 8c46b39a4aaa7a9c5584721a682f44f63fe45be1 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 31 Oct 2023 09:17:10 -0400 Subject: [PATCH 24/84] phep-0001: remove the idea of a "meta" PHEP * Process PHEPs would mostly be considered meta, as well as (probably) lots of standards ones...no sense confusing the issue. --- pheps/phep-0001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 84aa95e..365b010 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -35,7 +35,7 @@ There are three kinds of PHEP: 1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. 2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a new standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. -3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. Any meta-PHEP is also considered a Process PHEP. +3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. # PHEP Applicability **Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally should do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for acceptance. Standards track PHEP compliance should be considered as a factor in evaluating current and potential PyHC packages. @@ -83,7 +83,7 @@ The standard PHEP workflow is: If the PHEP isn't ready for approval, an editor will send it back to the author with specific instructions. -* Once approved, they will assign your PHEP a number. All PHEPs are sequentially-numbered at time of assignment. This includes meta-PHEPs. "Special" numbers (X, 0, etc.) are not used. Upon approval, the author must mark the PHEP PR ready for review. +* Once approved, they will assign your PHEP a number. All PHEPs are sequentially-numbered at time of assignment. "Special" numbers (X, 0, etc.) are not used. Upon approval, the author must mark the PHEP PR ready for review. The PHEP editors will not unreasonably deny approval of a PHEP. Reasons for denying PHEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the PyHC philosophy. From bc5ac28bb36c7493e9dd44ad3a0c7583de1ee6af Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 31 Oct 2023 09:20:10 -0400 Subject: [PATCH 25/84] phep-0001: one PHEP per PR --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 365b010..dd78a0a 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -73,7 +73,7 @@ The standard PHEP workflow is: * You, the PHEP author, fork the PyHC [standards](https://github.com/heliophysicsPy/standards) repository, and create a file named `phep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). -* Push this to a branch (not `main`) of your GitHub fork and submit a draft pull request. +* Push this to a branch (not `main`) of your GitHub fork and submit a draft pull request. Each PR must contain a single PHEP; open multiple PRs (from separate branches) if drafting multiple PHEPs. * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is 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. From dba76fa07077a3f778fb9ce64efa386d510dc64e Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 31 Oct 2023 09:30:26 -0400 Subject: [PATCH 26/84] phep-0001: add sections for rejected ideas, open issues --- pheps/phep-0001.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index dd78a0a..e7ec430 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -265,6 +265,18 @@ Disagreements with editors must be mediated by PyHC leadership (as documented in This PHEP is subject to the same review and acceptance process that it proposes. +# Rejected Ideas + +## ASCII encoding + +As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. + +# Open Issues + +## Immutability of PHEPs + +PHEPs are proposed to be [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This is not universally accepted. + # Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. From 4af2b621485d0ebb7ef4fb5aafb09544faae440a Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Tue, 31 Oct 2023 09:33:15 -0400 Subject: [PATCH 27/84] phep-0001: new post history entry for new push --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index e7ec430..9144187 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -7,7 +7,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023 +Post-History: 24-Oct-2023, 31-Oct-2023 ``` # What is a PHEP? From f8563e773eb5c479e4eef6f0129f35e5e155b8ee Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 1 Nov 2023 07:07:14 -0400 Subject: [PATCH 28/84] phep-0001: add anchors for all headings * Make it easier to link from outside documents. --- pheps/phep-0001.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 9144187..bf3863d 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -11,6 +11,7 @@ Post-History: 24-Oct-2023, 31-Oct-2023 ``` # What is a PHEP? + PHEP stands for PyHC Enhancement Proposal. A PHEP provides information to the Python in Heliophysics Community (PyHC), describes its processes, or establishes standards for its packages. The PHEP should provide a concise technical specification of the feature or standard and a rationale. PHEPs are the primary mechanism for proposing standards, for collecting community input, and for documenting the design decisions underlying PyHC standards and recommendations. The PHEP process develops and documents consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. @@ -18,6 +19,7 @@ PHEPs are the primary mechanism for proposing standards, for collecting communit Because PHEPs 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. # PHEP Motivation + The [PyHC standards](https://doi.org/10.5281/zenodo.2529131) have not been updated since their initial approval in 2018, and there is no established process for updating them. PyHC discussions often involve what packages "should" do, or "should be required" to do. For standards to be effective, they need to be seen as legitimate by those they may be imposed on. A mechanism is needed to capture the sense of the community and allow it to progress while recognizing that the community is broad, diffuse, and diverse, and not all stakeholders are present for all conversations. @@ -31,6 +33,7 @@ However, other parts of the PyHC community (hereafter "community") may also use This PHEP refers to "PyHC leadership": individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or other individuals or groups appropriately designated in the future, such as a steering committee. # PHEP Types + There are three kinds of PHEP: 1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. @@ -38,6 +41,7 @@ There are three kinds of PHEP: 3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. # PHEP Applicability + **Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally should do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for acceptance. Standards track PHEP compliance should be considered as a factor in evaluating current and potential PyHC packages. **Informational** PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. @@ -47,6 +51,7 @@ There are three kinds of PHEP: For all three kinds, key words in PHEPs must be interpreted according to [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119); the use of `must`, `must not`, `should`, and `should not` are preferred to the alternatives. # PHEP Workflow + ## PHEP Editors PHEP editors are responsible for managing the administrative and editorial aspects of the PHEP workflow (e.g. assigning PHEP numbers and changing their status). See [PHEP Editor Responsibilities & Workflow](#phep-editor-responsibilities-workflow) for details. @@ -56,6 +61,7 @@ PHEP editorship is by nomination of the current editors, subject to approval by The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on GitHub. All PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. ## Start with an idea + The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. Each PHEP must have an author - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include discussion on a PyHC telecon, posting to the PyHC mailing list, asking on PyHC Element/Slack, and [opening an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should then be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic and this informal discussion may happen in multiple places. @@ -67,6 +73,7 @@ Early vetting allows PHEP authors to collecting community feedback while avoidin Once the author has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be submitted as described below. This gives the author a chance to flesh out the draft PHEP to make it properly formatted, of high quality, and to address initial concerns about the proposal. ## Submitting a PHEP + The proposal must be submitted as a draft PHEP via a [GitHub pull request](https://github.com/heliophysicsPy/standards/pulls). The draft must be written in PHEP style as described below. The editors may correct minor errors. The standard PHEP workflow is: @@ -90,6 +97,7 @@ The PHEP editors will not unreasonably deny approval of a PHEP. Reasons for deny Standards Track PHEPs may consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation in an existing or new PyHC package be co-developed with the PHEP, as ideas that sound good in principle sometimes turn out to be impractical when implemented. ## Discussing a PHEP + Once the draft PHEP is submitted in an open PR and a PHEP number has been assigned, the PR discussion thread provides the central place to discuss and review its contents. The PHEP must be updated so that the `Discussions-To` header links to the PR. The discussion must also be announced by the PHEP authors via reasonable means; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Element/Slack. Informal conversation may happen in the PyHC mailing list, Element/Slack, or private side channels. However, the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and any side conversations should ultimately result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the PHEP review process. Feedback on this designated thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". @@ -103,6 +111,7 @@ If a PHEP undergoes a significant re-write or other major changes, the author(s) PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). ## PHEP Review & Resolution + Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community. A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via comment on the PR. A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. @@ -146,6 +155,7 @@ Changes to PHEPs in the Final state are limited to the preamble, and only in the Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. # What belongs in a successful PHEP? + Each PHEP should have the following elements, where they are applicable. It is suggested, but not required, that each element be addressed in a dedicated section of the PHEP. 1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, described [below](#phep-header-preamble). @@ -173,6 +183,7 @@ Each PHEP should have the following elements, where they are applicable. It is s 13. Copyright/license - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). # PHEP Formats and Templates + PHEPs are UTF-8 encoded text files using the Markdown format. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). The PHEP text files are automatically rendered by the GitHub interface for easier online reading. The Markdown source is the version of record. @@ -228,6 +239,7 @@ PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP dep PHEPs may also have a Replaced-By header indicating that a PHEP has been rendered obsolete by a later document; the value is the number of the PHEP that replaces the current document. The newer PHEP must have a Replaces header containing the number of the PHEP that it rendered obsolete. # Auxiliary Files + PHEPs may include auxiliary files such as diagrams. Such files should be named `phep-XXXX-Y.ext`, where "XXXX" is the PHEP 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 `phep-XXXX`, where "XXXX" is the PHEP number. When using a subdirectory, there are no constraints on the names used in files. @@ -262,22 +274,24 @@ PHEP editors do not make judgments on the content or merits of PHEPs. They merel Disagreements with editors must be mediated by PyHC leadership (as documented in [PHEP audience](#phep-audience)) and they may impose sanctions, including removal of the editor role. # PHEP 1 Acceptance - + This PHEP is subject to the same review and acceptance process that it proposes. # Rejected Ideas + ## ASCII encoding - + As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. # Open Issues - + ## Immutability of PHEPs - + PHEPs are proposed to be [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This is not universally accepted. # Copyright + This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. This document draws from: From 9c32fd11b4af009c0eca75df6aca67dd761456ab Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 1 Nov 2023 07:11:30 -0400 Subject: [PATCH 29/84] phep-0001: improve readability of sections-of-phep by bolding titles --- pheps/phep-0001.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index bf3863d..8584343 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -158,29 +158,29 @@ Preamble changes are made via PR to the `standards` repository, merged by PHEP e Each PHEP should have the following elements, where they are applicable. It is suggested, but not required, that each element be addressed in a dedicated section of the PHEP. -1. Preamble - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, described [below](#phep-header-preamble). -2. Abstract - a short (~200 word) description of the issue being addressed. -3. Motivation - The motivation must clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. +1. **Preamble** - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, described [below](#phep-header-preamble). +2. **Abstract** - a short (~200 word) description of the issue being addressed. +3. **Motivation** - The motivation must clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. 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 completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. -6. Backwards Compatibility - All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. -7. Security Implications - Any security concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. -8. How to Teach This - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work. +5. **Specification** - The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. +6. **Backwards Compatibility** - All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. +7. **Security Implications** - Any security concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. +8. **How to Teach This** - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work. -9. Reference Implementation - The reference implementation must be completed before any PHEP is given status "Final", but it need not be completed before the PHEP 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. +9. **Reference Implementation** - The reference implementation must be completed before any PHEP is given status "Final", but it need not be completed before the PHEP 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 the relevant PyHC project(s). -10. Rejected Ideas - Throughout the discussion of a PHEP, various ideas will be proposed which are not incorporated. 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 PHEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions. +10. **Rejected Ideas** - Throughout the discussion of a PHEP, various ideas will be proposed which are not incorporated. 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 PHEP 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 a PHEP 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 PHEP to be ready for consideration are complete and reduces people duplicating prior discussion. -12. Footnotes - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. -13. Copyright/license - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). +11. **Open Issues** - While a PHEP 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 PHEP to be ready for consideration are complete and reduces people duplicating prior discussion. +12. **Footnotes** - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. +13. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). # PHEP Formats and Templates From a32abab9024cc315a8496994bebbcdec6a3196f4 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 1 Nov 2023 07:13:47 -0400 Subject: [PATCH 30/84] phep-0001: fix link to CC0 --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 8584343..4ec1ab7 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -180,7 +180,7 @@ Each PHEP should have the following elements, where they are applicable. It is s 11. **Open Issues** - While a PHEP 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 PHEP to be ready for consideration are complete and reduces people duplicating prior discussion. 12. **Footnotes** - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. -13. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://choosealicense.com/licenses/cc0-1.0/) (see this PHEP for an example). +13. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) (see this PHEP for an example). # PHEP Formats and Templates From 9275cf7f3549455d5bd22ba5571c80665fed6e77 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 1 Nov 2023 07:22:30 -0400 Subject: [PATCH 31/84] phep-0001: remove unworkable promise to hide email addresses --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 4ec1ab7..ad7df22 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -224,7 +224,7 @@ if the email address is included, and just: if the address is not given. -If there are multiple authors, each should be on a separate line following [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions. Note that personal email addresses in PHEPs will be obscured as a defense against spam harvesters. +If there are multiple authors, each should be on a separate line following [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions. The Discussions-To header provides the URL to the current PR discussion thread for the PHEP. From df76954ada64ea4da5b468e3cbbfad8dcb34e022 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Sun, 5 Nov 2023 12:42:15 -0500 Subject: [PATCH 32/84] phep-0001: replace hyphen after author with colon --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index ad7df22..30d6654 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -64,7 +64,7 @@ The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on Git The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have an author - someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include discussion on a PyHC telecon, posting to the PyHC mailing list, asking on PyHC Element/Slack, and [opening an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should then be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic and this informal discussion may happen in multiple places. +Each PHEP must have an author: someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include discussion on a PyHC telecon, posting to the PyHC mailing list, asking on PyHC Element/Slack, and [opening an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should then be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic and this informal discussion may happen in multiple places. Vetting an idea publicly before writing a PHEP is meant to save the author time. Asking the community first if an idea is original helps prevent too much time being spent on something that may 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. Just because an idea sounds good to the author does not mean it will work for most people in most areas. From c1d450a336bf90c73045fa1c5bde79af5b36d1c4 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 11:15:25 -0500 Subject: [PATCH 33/84] phep-0001: remove picky markdown formatting notes --- pheps/phep-0001.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 30d6654..f27a259 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -84,7 +84,7 @@ The standard PHEP workflow is: * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is 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 PHEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant. PHEPs with invalid Markdown (MD) markup will not be approved; here "invalid" include Markdown which provides clearly unintended output (in the discretion of the editors). + * The PHEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant. Markdown (MD) markup and other formatting should be clear and reasonable. Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. Correctness is the responsibility of authors and reviewers, not the editors. @@ -186,10 +186,6 @@ Each PHEP should have the following elements, where they are applicable. It is s PHEPs are UTF-8 encoded text files using the Markdown format. A future PHEP may include a template. PHEP Markdown must be compatible with the most recent version of the [CommonMark specification](https://spec.commonmark.org/) at the time the PHEP is approved. PHEPs must not use [GitHub extensions](https://github.github.com/gfm/). -The PHEP text files are automatically rendered by the GitHub interface for easier online reading. The Markdown source is the version of record. - -The readability of the diff should be considered when editing a PHEP. - The editors are responsible for enforcing PHEP format and consistency of style within a PHEP. They may use automated tools (e.g. pre-commit hooks) to assist. # PHEP Header Preamble @@ -258,7 +254,7 @@ For each new PHEP that comes in, an editor does the following: * Read the PHEP 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. `.md`). -* Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.). Editors may correct problems themselves, but are not required to do so. +* Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.) or formatting. Editors may correct problems themselves, but are not required to do so. * If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. This is to avoid a PHEP accidentally portraying a project as supporting a PHEP when in fact the support is based on conjecture. If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. @@ -284,6 +280,10 @@ This PHEP is subject to the same review and acceptance process that it proposes. As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. +## Source formatting + +Certain ideas regarding the format of the Markdown source were removed as more complicated than their benefit: making the source the version of record over the rendered, notes on specifics of rendering, and trying to get pretty diffs of Markdown. + # Open Issues ## Immutability of PHEPs From 0a933708d4213db1284de6e2bde1c5b950913a0e Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 11:51:18 -0500 Subject: [PATCH 34/84] phep-0001: add ORCID --- pheps/phep-0001.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index f27a259..6372b81 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -1,7 +1,7 @@ ``` PHEP: 1 Title: PHEP Purpose and Guidelines -Author: Jonathan Niehof +Author: Jonathan Niehof Discussions-To: https://github.com/heliophysicsPy/standards/pull/22 Status: Draft Type: Process @@ -210,15 +210,15 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf * Resolution: ``` -The Author header lists the names and optionally the email addresses of all the authors/owners of the PHEP. The format of the Author header values must be: +The Author header lists the names and optionally the email addresses and/or [ORCIDs](https://orcid.org) of all the authors of the PHEP. The format of the Author header values must be: -`Random J. User ` +`Random J. User ` -if the email address is included, and just: +if the email address and ORCID are included, and just: `Random J. User` -if the address is not given. +for just the name (similarly for ORCID without email address and vice versa). If there are multiple authors, each should be on a separate line following [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions. From 9c3cec45a4131723b9dd5a2936db3c5664da3c72 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 11:57:09 -0500 Subject: [PATCH 35/84] phep-0001: reject recording all names of approvers --- pheps/phep-0001.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 6372b81..00b75e4 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -280,6 +280,10 @@ This PHEP is subject to the same review and acceptance process that it proposes. As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. +## Recording names at acceptance + +There was consideration of recording the names of people present when a PHEP is accepted, or who specifically want to "sign on". This was decided to be out-of-scope for the PHEP process; the notes of the meeting should capture relevant information. + ## Source formatting Certain ideas regarding the format of the Markdown source were removed as more complicated than their benefit: making the source the version of record over the rendered, notes on specifics of rendering, and trying to get pretty diffs of Markdown. From 57d6e6ee4bfe9bfd00d22cf1f7419c308f7e2584 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 12:02:36 -0500 Subject: [PATCH 36/84] phep-0001: mint a DOI! --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 00b75e4..4b978b6 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -140,7 +140,7 @@ The possible paths of the status of PHEPs are as follows: While not shown in the diagram, "Accepted" PHEPs 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 PHEP. -Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main`. +Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main`. They mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. ## PHEP Maintenance From 08271ea8f974f78a423c181b987cb670bf6d961d Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 12:16:31 -0500 Subject: [PATCH 37/84] phep-0001: add citation --- pheps/phep-0001.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 4b978b6..cb8eb27 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -296,7 +296,17 @@ PHEPs are proposed to be [immutable](#phep-maintenance) once Final, requiring re # Copyright -This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. +This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. It should be cited as: +``` +@techreport(phep1, + author = {Jonathan T. Niehof}, + title = {PHEP Purpose and Guidelines}, + year = {2023}, + type = {PHEP}, + number = {1}, + doi = {10.5281/zenodo.xxxxxxx} +) +``` This document draws from: From 174346edaa299de7ce3630f8d70e044dc7c38fe9 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 14:14:48 -0500 Subject: [PATCH 38/84] phep-0001: aux files in subdirectory only * Simplify things a bit --- pheps/phep-0001.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index cb8eb27..2811088 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -236,8 +236,7 @@ PHEPs may also have a Replaced-By header indicating that a PHEP has been rendere # Auxiliary Files -PHEPs may include auxiliary files such as diagrams. Such files should be named `phep-XXXX-Y.ext`, where "XXXX" is the PHEP 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 `phep-XXXX`, where "XXXX" is the PHEP number. When using a subdirectory, there are no constraints on the names used in files. +PHEPs may include auxiliary files such as diagrams. Such files must be placed in a subdirectory called `phep-XXXX`, where "XXXX" is the PHEP number. There are no constraints on the names used in files. # Transferring PHEP Ownership From 037184e022e2ccbb02ce41d4035379c00a153eeb Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 14:39:42 -0500 Subject: [PATCH 39/84] phep-0001: clarify and remove redundancies --- pheps/phep-0001.md | 89 +++++++++++++++++++++------------------------- 1 file changed, 41 insertions(+), 48 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 2811088..f85f38e 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -12,11 +12,11 @@ Post-History: 24-Oct-2023, 31-Oct-2023 # What is a PHEP? -PHEP stands for PyHC Enhancement Proposal. A PHEP provides information to the Python in Heliophysics Community (PyHC), describes its processes, or establishes standards for its packages. The PHEP should provide a concise technical specification of the feature or standard and a rationale. +PHEP stands for PyHC Enhancement Proposal. A PHEP provides information to the Python in Heliophysics Community (PyHC), describes its processes, or establishes standards for its packages. -PHEPs are the primary mechanism for proposing standards, for collecting community input, and for documenting the design decisions underlying PyHC standards and recommendations. The PHEP process develops and documents consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. +PHEPs are the primary mechanism for proposing standards, collecting community input, and documenting the design decisions underlying PyHC standards and recommendations. The PHEP process develops and documents consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. -Because PHEPs 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. +Because PHEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This record is available by the normal git commands for retrieving older revisions and can be browsed on GitHub. # PHEP Motivation @@ -26,51 +26,51 @@ A mechanism is needed to capture the sense of the community and allow it to prog # PHEP Audience -The typical audience for PHEPs is the developers and user communities of PyHC packages. - -However, other parts of the PyHC community (hereafter "community") may also use the process (particularly for Informational PHEPs) to document conventions and to manage complex design coordination problems that require collaboration across multiple projects. +The typical audience for PHEPs is the developers and user communities of PyHC packages. Other parts of the PyHC community (hereafter "community") may also use the process (particularly for Informational PHEPs) to document conventions and to manage complex design coordination problems that require collaboration across multiple projects. This PHEP refers to "PyHC leadership": individuals or groups with statutory authority over the PyHC project. This may be the Principal Investigator or other individuals or groups appropriately designated in the future, such as a steering committee. # PHEP Types -There are three kinds of PHEP: +There are three types of PHEP: 1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. -2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a new standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. +2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. 3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. # PHEP Applicability -**Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally should do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for acceptance. Standards track PHEP compliance should be considered as a factor in evaluating current and potential PyHC packages. +**Standards** Track PHEPs are recommended standards for PyHC packages. Most packages should make a good-faith effort to comply. PyHC core packages are strongly recommended to comply and generally must do so, absent a compelling reason not to. A PHEP which core packages cannot agree to implement likely does not have sufficient community support for acceptance. Standards track PHEP compliance must be considered as a factor in evaluating current and potential PyHC packages. **Informational** PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. **Process** PHEPs determine the process by which the PyHC community makes formal decisions and as such bind all participants in PyHC. -For all three kinds, key words in PHEPs must be interpreted according to [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119); the use of `must`, `must not`, `should`, and `should not` are preferred to the alternatives. +For all three types, key words in PHEPs must be interpreted according to [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119); the use of `must`, `must not`, `should`, and `should not` are preferred. # PHEP Workflow + All PHEP workflow is conducted via the [GitHub PyHC standards repository](https://github.com/heliophysicsPy/standards). + ## PHEP Editors PHEP editors are responsible for managing the administrative and editorial aspects of the PHEP workflow (e.g. assigning PHEP numbers and changing their status). See [PHEP Editor Responsibilities & Workflow](#phep-editor-responsibilities-workflow) for details. PHEP editorship is by nomination of the current editors, subject to approval by PyHC leadership. In the event there are fewer than two active editors, PyHC leadership may appoint editors from active participants in the community, sufficient to bring the total to two. -The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on GitHub. All PHEP workflow is conducted via the GitHub PyHC standards repository issues and pull requests. +The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on GitHub. ## Start with an idea -The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. The PHEP editors reserve the right to reject PHEP proposals if they appear too unfocused or too broad. If in doubt, split your PHEP into several well-focused ones. +The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have an author: someone who writes the PHEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include discussion on a PyHC telecon, posting to the PyHC mailing list, asking on PyHC Element/Slack, and [opening an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should then be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic and this informal discussion may happen in multiple places. +Each PHEP must have an author: someone who writes the PHEP using the style and format described below, shepherds the discussion, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include a PyHC [telecon](https://heliopython.org/meetings/), the PyHC [mailing list](https://heliopython.org/contact/), PyHC [Matrix/Slack](https://riot.im/app/#/room/#heliopython:openastronomy.org), and [an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic. -Vetting an idea publicly before writing a PHEP is meant to save the author time. Asking the community first if an idea is original helps prevent too much time being spent on something that may 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. Just because an idea sounds good to the author does not mean it will work for most people in most areas. +Vetting an idea publicly before writing a PHEP is meant to save the author time. Asking the community first helps prevent too much time being spent on something that may 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. -Early vetting allows PHEP authors to collecting community feedback while avoiding 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 PHEP's subject matter, and picking an appropriately-specialized discussion for the PHEP's topic (if applicable) should be considered. +Early vetting allows PHEP authors to collect community feedback while avoiding long-winded and open-ended discussions. Strategies such as soliciting private or narrowly-tailored feedback in the early design phase, collaborating with other community members with expertise in the PHEP's subject matter, and picking an appropriately-specialized discussion for the PHEP's topic should be considered. -Once the author has asked the PyHC community as to whether an idea has any chance of acceptance, a draft PHEP should be submitted as described below. This gives the author a chance to flesh out the draft PHEP to make it properly formatted, of high quality, and to address initial concerns about the proposal. +Once the author has asked the community whether an idea has any chance of acceptance, a draft PHEP should be submitted as described below. This gives the author a chance to flesh out the draft PHEP to make it properly formatted, of high quality, and to address initial concerns about the proposal. ## Submitting a PHEP @@ -83,6 +83,7 @@ The standard PHEP workflow is: * Push this to a branch (not `main`) of your GitHub fork and submit a draft pull request. Each PR must contain a single PHEP; open multiple PRs (from separate branches) if drafting multiple PHEPs. * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. + * It is of reasonable scope, not too broad or unfocused. * The title accurately describes the content. * The PHEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant. Markdown (MD) markup and other formatting should be clear and reasonable. @@ -98,11 +99,11 @@ Standards Track PHEPs may consist of two parts, a design document and a referenc ## Discussing a PHEP -Once the draft PHEP is submitted in an open PR and a PHEP number has been assigned, the PR discussion thread provides the central place to discuss and review its contents. The PHEP must be updated so that the `Discussions-To` header links to the PR. The discussion must also be announced by the PHEP authors via reasonable means; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Element/Slack. +Once the draft PHEP is submitted in an open PR and a PHEP number has been assigned, the PR discussion thread provides the central place to discuss and review its contents. The PHEP must be updated so that the `Discussions-To` header links to the PR. The discussion must also be announced by the PHEP authors via reasonable means; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Matrix/Slack. -Informal conversation may happen in the PyHC mailing list, Element/Slack, or private side channels. However, the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and any side conversations should ultimately result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the PHEP review process. Feedback on this designated thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". +Informal conversation may elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". -PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. Rebasing of history before a push for greater clarity is acceptable. +PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. PHEP authors are responsible for managing the progress of the discussion of their PHEP, for instance by updating the PR description to highlight topics of particular interest and to provide the dates of votes on the PHEP resolution. @@ -112,25 +113,21 @@ PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.o ## PHEP Review & Resolution -Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is ultimately the responsibility of the community. A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via comment on the PR. +Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is the responsibility of the community. A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via comment on the PR. A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. -"Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make a compelling case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. +"Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make the case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. For a PHEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed change. The change must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. ("Pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) -The editors must post announcements of PHEP resolution to the PyHC mailing list. - Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final" upon acceptance. -If a PHEP requires additional design and interface feedback before committing to long term stability, it must remain in "Draft". Alternatively, its scope can be reduced (e.g. by deferring some features to later PHEPs). - If no progress is being made on the PHEP, the editor should consult the author. The author may resume work on the PHEP, [transfer it to another author](transferring-phep-ownership), or withdraw it. If the author takes none of these actions, the editor may choose to bring the PHEP to the community for acceptance or rejection in its current form. -If a PHEP fails to find consensus, the author may choose to modify it for reconsideration in the future. The PHEP may also be "Withdrawn" if the PHEP author themself decides that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also be "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. +If a PHEP fails to find consensus, the author may choose to modify it for reconsideration. The PHEP may be "Withdrawn" if the PHEP author themself decides that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. -When a PHEP changes state, the PHEP preamble must be updated accordingly. In addition to updating the Status field, the Resolution header must be added with a direct link to the minutes of the telecons and meetings where a decision on the PHEP was made. +When a PHEP changes state, the PHEP preamble must be updated accordingly. In addition to updating the Status field, the Resolution header must be added with a direct link to the minutes of the telecons and meetings where a decision on the PHEP was made. The editors must post announcements of PHEP resolution to the PyHC mailing list. Final PHEPs can also be replaced by a different PHEP, rendering the original obsolete. @@ -138,25 +135,23 @@ The possible paths of the status of PHEPs are as follows: ![PHEP status flow diagram](phep-0001/process_flow.svg) -While not shown in the diagram, "Accepted" PHEPs 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 PHEP. +"Accepted" PHEPs 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 PHEP. Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main`. They mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. ## PHEP Maintenance -PHEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected, Withdrawn, or Replaced state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. +PHEPs are no longer substantially modified after they have left the Draft state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. If changes based on implementation experience and user feedback are made to PHEPs while in the Accepted state, they should be noted in the PHEP, such that the PHEP accurately describes the implementation at the point where it is marked Final. Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. -Changes to PHEPs in the Final state are limited to the preamble, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. - -Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. +Changes to PHEPs in the Final state are limited to the preamble, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. # What belongs in a successful PHEP? -Each PHEP should have the following elements, where they are applicable. It is suggested, but not required, that each element be addressed in a dedicated section of the PHEP. +Each PHEP should have the following elements, where they are applicable. It is suggested that each element be addressed in a dedicated section of the PHEP. 1. **Preamble** - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, described [below](#phep-header-preamble). 2. **Abstract** - a short (~200 word) description of the issue being addressed. @@ -166,21 +161,19 @@ Each PHEP should have the following elements, where they are applicable. It is s 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 completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. -6. **Backwards Compatibility** - All PHEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. -7. **Security Implications** - Any security concerns should be explicitly written out to make sure reviewers of the PHEP are aware of them. +6. **Backwards Compatibility** - All PHEPs that introduce backwards incompatibilities must describe these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. +7. **Security Implications** - Any security concerns should be explicitly written out. 8. **How to Teach This** - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work. 9. **Reference Implementation** - The reference implementation must be completed before any PHEP is given status "Final", but it need not be completed before the PHEP 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 the relevant PyHC project(s). -10. **Rejected Ideas** - Throughout the discussion of a PHEP, various ideas will be proposed which are not incorporated. 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 PHEP 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. +10. **Rejected Ideas** - Throughout the discussion of a PHEP, various ideas will be proposed which are not incorporated. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This helps record the thought process behind the final version of the PHEP and prevents people from bringing up the same rejected idea again in subsequent discussions. -11. **Open Issues** - While a PHEP 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 PHEP to be ready for consideration are complete and reduces people duplicating prior discussion. +11. **Open Issues** - While a PHEP 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 PHEP to be ready for consideration are complete. 12. **Footnotes** - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. -13. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) (see this PHEP for an example). +13. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) and include citation information (see this PHEP for an example). # PHEP Formats and Templates @@ -190,7 +183,7 @@ The editors are responsible for enforcing PHEP format and consistency of style w # PHEP Header Preamble -Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style header preamble, marked off with a [code fence](https://spec.commonmark.org/current/#fenced-code-blocks). The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required. +Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style header preamble, marked off with a [code fence](https://spec.commonmark.org/current/#fenced-code-blocks). The headers must appear in the following order. Headers marked with "*" are optional. All other headers are required. ``` PHEP: @@ -224,11 +217,11 @@ If there are multiple authors, each should be on a separate line following [RFC The Discussions-To header provides the URL to the current PR discussion thread for the PHEP. -The Type header specifies the type of PHEP: Standards Track, Informational, or Process. +The Type header specifies the [type](#phep-type) of PHEP: Standards Track, Informational, or Process. The format of a PHEP is specified with a Content-Type header. All PHEPs must use Markdown, and have a value of `text/markdown; charset=UTF-8; variant=CommonMark`. -The Created header records the date that the PHEP was assigned a number, while Post-History is used to record the dates of pushes to the pull request for the PHEP, with the former as the linked text. Both sets of dates should be in `dd-mmm-yyyy` format, e.g. `14-Aug-2001`. +The Created header records the date that the PHEP was assigned a number, while Post-History is used to record the dates of pushes to the pull request for the PHEP. Both sets of dates should be in `dd-mmm-yyyy` format, e.g. `14-Aug-2001`. PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP depends on. @@ -240,9 +233,9 @@ PHEPs may include auxiliary files such as diagrams. Such files must be placed in # Transferring PHEP Ownership -It occasionally becomes necessary to transfer ownership of PHEPs to a new author. In general, it is preferable to retain the original author as a co-author of the transferred PHEP, at their discretion. 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 PHEP process, or 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 PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that's not possible, an author can always submit a competing PHEP. +It occasionally becomes necessary to transfer ownership of PHEPs to a new author. It is preferable to retain the original author as a co-author of the transferred PHEP, at their discretion. 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 PHEP process, or is unreachable. A bad reason to transfer ownership is because the author doesn't agree with the direction of the PHEP. One aim of the PHEP process is to try to build consensus around a PHEP, but if that's not possible, an author can always submit a competing PHEP. -If you are interested in assuming ownership of a PHEP, you can do this via the pull request discussion thread. Mention both the original author and `@heliophysicsPy/phep-editors` in a comment on the pull request. If the original author doesn't respond in a timely manner, the PHEP editors will make a unilateral decision, which can be reversed. +If you are interested in assuming ownership of a PHEP, mention the original author and `@heliophysicsPy/phep-editors` in a comment on the PHEP's pull request. If the original author doesn't respond in a timely manner, the PHEP editors will make a unilateral decision, which can be reversed. # PHEP Editor Responsibilities & Workflow @@ -252,16 +245,16 @@ For each new PHEP that comes in, an editor does the following: * Read the PHEP 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 PHEP's type is correctly labeled ("Standards Track", "Informational", or "Process"), and its status is "Draft". * The file name extension is correct (i.e. `.md`). * Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.) or formatting. Editors may correct problems themselves, but are not required to do so. -* If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. This is to avoid a PHEP accidentally portraying a project as supporting a PHEP when in fact the support is based on conjecture. +* If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. Once the PHEP is ready for discussion, a PHEP editor will: -* Assign a PHEP number (almost always just the next available number). -* Check that the author has correctly labeled the PHEP's type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft". +* Assign a PHEP number (almost always the next available number). * Ask the author to update the PHEP with the PR link, mark the PR ready for review, and post an announcement. PHEP editors do not make judgments on the content or merits of PHEPs. They merely do the administrative & editorial part. They may participate in the community discussion of a PHEP but have no obligation to be advocates. From 1538d180fa5ee143a5e3471b39d35223177d3040 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 14:42:48 -0500 Subject: [PATCH 40/84] phep-0001: make each list item a paragraph * The inconsistency was getting to me.... --- pheps/phep-0001.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index f85f38e..f1b7a4a 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -35,7 +35,9 @@ This PHEP refers to "PyHC leadership": individuals or groups with statutory auth There are three types of PHEP: 1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. + 2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. + 3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. # PHEP Applicability @@ -79,8 +81,11 @@ The proposal must be submitted as a draft PHEP via a [GitHub pull request](https The standard PHEP workflow is: * You, the PHEP author, fork the PyHC [standards](https://github.com/heliophysicsPy/standards) repository, and create a file named `phep-9999.md` that contains your new PHEP. Use "9999" as your draft PHEP 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 [PHEP Header Preamble](#phep-header-preamble). + * Push this to a branch (not `main`) of your GitHub fork and submit a draft pull request. Each PR must contain a single PHEP; open multiple PRs (from separate branches) if drafting multiple PHEPs. + * The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: * It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. * It is of reasonable scope, not too broad or unfocused. @@ -154,15 +159,21 @@ Changes to PHEPs in the Final state are limited to the preamble, and only in the Each PHEP should have the following elements, where they are applicable. It is suggested that each element be addressed in a dedicated section of the PHEP. 1. **Preamble** - [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822.html) style headers containing metadata about the PHEP, described [below](#phep-header-preamble). + 2. **Abstract** - a short (~200 word) description of the issue being addressed. + 3. **Motivation** - The motivation must clearly explain why the existing standards are inadequate to address the problem that the PHEP solves. This can include collecting documented support for the PHEP from important projects in the PyHC ecosystem. PHEP 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. 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 completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. + 6. **Backwards Compatibility** - All PHEPs that introduce backwards incompatibilities must describe these incompatibilities and their severity. The PHEP must explain how the author proposes to deal with these incompatibilities. + 7. **Security Implications** - Any security concerns should be explicitly written out. + 8. **How to Teach This** - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work. 9. **Reference Implementation** - The reference implementation must be completed before any PHEP is given status "Final", but it need not be completed before the PHEP 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. @@ -172,7 +183,9 @@ Each PHEP should have the following elements, where they are applicable. It is s 10. **Rejected Ideas** - Throughout the discussion of a PHEP, various ideas will be proposed which are not incorporated. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This helps record the thought process behind the final version of the PHEP and prevents people from bringing up the same rejected idea again in subsequent discussions. 11. **Open Issues** - While a PHEP 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 PHEP to be ready for consideration are complete. + 12. **Footnotes** - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. + 13. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) and include citation information (see this PHEP for an example). # PHEP Formats and Templates @@ -244,10 +257,15 @@ A PHEP editor must be added to the `@heliophysicsPy/phep-editors` group on GitHu For each new PHEP that comes in, an editor does the following: * Read the PHEP 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 PHEP's type is correctly labeled ("Standards Track", "Informational", or "Process"), and its status is "Draft". + * The file name extension is correct (i.e. `.md`). + * Skim the PHEP for obvious defects in language (spelling, grammar, sentence structure, etc.) or formatting. Editors may correct problems themselves, but are not required to do so. + * If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. @@ -255,6 +273,7 @@ If the PHEP isn't ready, an editor will send it back to the author for revision, Once the PHEP is ready for discussion, a PHEP editor will: * Assign a PHEP number (almost always the next available number). + * Ask the author to update the PHEP with the PR link, mark the PR ready for review, and post an announcement. PHEP editors do not make judgments on the content or merits of PHEPs. They merely do the administrative & editorial part. They may participate in the community discussion of a PHEP but have no obligation to be advocates. From 75866b1a4b0f5e96b154ccc0e26d0e4a2f5df368 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 14:49:30 -0500 Subject: [PATCH 41/84] phep-0001: add general rationale --- pheps/phep-0001.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index f1b7a4a..34419d9 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -284,6 +284,10 @@ Disagreements with editors must be mediated by PyHC leadership (as documented in This PHEP is subject to the same review and acceptance process that it proposes. +# Rationale + +PHEP 1 is based on [PEP 1](https://peps.python.org/pep-0001/), which is a process that has credibility in the Python community and has proven appropriate for a fairly large group, the PyHC community being (by definition) larger than the community for any one PyHC package. From this basis, changes were made to make the process relevant to PyHC and to streamline where practicable. + # Rejected Ideas From 5bfe9991213e87c47f5fc87cf2341095603018ce Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 14:59:38 -0500 Subject: [PATCH 42/84] phep-0001: provide pros/cons for immutability --- pheps/phep-0001.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 34419d9..71ca788 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -309,6 +309,14 @@ Certain ideas regarding the format of the Markdown source were removed as more c PHEPs are proposed to be [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This is not universally accepted. +### In favor +Immutability maintains clarity of reference, "PHEP-x" rather than "PHEP-x version y", and avoids confusion arising from rolling updates. It encourages getting the PHEP correct before first acceptance. Finally, it removes the need to define and document an update process. + +A PHEP can be updated by introducing a new PHEP that starts with and builds on the original text. Everything is then open for discussion. This encourages complete re-evaluation if the community reaches the point where something is important enough to revisit, and discourages fixing a typo that doesn't hurt anything. + +### Opposed +Immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. + # Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. It should be cited as: From 0cd4f81ca4dd6b498606aadb3bbe451bd0031b9b Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 15:02:06 -0500 Subject: [PATCH 43/84] phep-0001: new post history for new push --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 71ca788..91d09ea 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -7,7 +7,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023 +Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023 ``` # What is a PHEP? From 1a2a02226b1c1b117fd7addc7566f6fb077b07b5 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 15:47:39 -0500 Subject: [PATCH 44/84] phep-0001: restore missing word --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 91d09ea..7730b97 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -106,7 +106,7 @@ Standards Track PHEPs may consist of two parts, a design document and a referenc Once the draft PHEP is submitted in an open PR and a PHEP number has been assigned, the PR discussion thread provides the central place to discuss and review its contents. The PHEP must be updated so that the `Discussions-To` header links to the PR. The discussion must also be announced by the PHEP authors via reasonable means; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Matrix/Slack. -Informal conversation may elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". +Informal conversation may happen elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. From 7b9820e5b6ccc01b31204ca64b135eb4c75ed210 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 9 Nov 2023 15:55:57 -0500 Subject: [PATCH 45/84] phep-0001: consistency in author name --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 7730b97..7c09d4a 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -1,7 +1,7 @@ ``` PHEP: 1 Title: PHEP Purpose and Guidelines -Author: Jonathan Niehof +Author: Jonathan T. Niehof Discussions-To: https://github.com/heliophysicsPy/standards/pull/22 Status: Draft Type: Process From 562680337df1f2fccdd2cfb5016dc3f226815eb6 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:38:01 -0500 Subject: [PATCH 46/84] phep-0001: Clarify consensus-before-vote and two-round procedure if edited --- pheps/phep-0001.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 7c09d4a..2cd2efa 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -118,7 +118,9 @@ PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.o ## PHEP Review & Resolution -Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is the responsibility of the community. A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, with no edits to the PHEP occurring in between. Any edits "reset the clock" and two further votes must be taken. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via comment on the PR. +Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is the responsibility of the community. It should be clear from the [discussion](#discussing-a-phep) when the community is beginning to agree: concerns have been addressed and new ones are not being raised, PR reviews with "approve" status are appearing, discussion is quieting down. At this point the PHEP author should seek formal acceptance. + +A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, with no edits to the PHEP occurring in between. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via comment on the PR. The PHEP may be edited up until the initial vote, for instance to incorporate discussion at the meeting. However, any edits after a vote invalidate that acceptance, and two further votes (one at a meeting, one on a telecon) must be taken. A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. From 5d30d3a4a0f87a84d7c9856828c265e6c5b78a7b Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:40:59 -0500 Subject: [PATCH 47/84] phep-0001: link standards repo in abstract --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 2cd2efa..9c7ab7c 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -16,7 +16,7 @@ PHEP stands for PyHC Enhancement Proposal. A PHEP provides information to the Py PHEPs are the primary mechanism for proposing standards, collecting community input, and documenting the design decisions underlying PyHC standards and recommendations. The PHEP process develops and documents consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. -Because PHEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This record is available by the normal git commands for retrieving older revisions and can be browsed on GitHub. +Because PHEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This record is available by the normal git commands for retrieving older revisions and can be browsed [on GitHub](https://github.com/heliophysicsPy/standards). # PHEP Motivation From 5f4dd861d0b8f61447ab0e0da8ae7a19aa42498d Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:41:51 -0500 Subject: [PATCH 48/84] phep-0001: editors must maintain history on merge --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 9c7ab7c..a8a0b3d 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -144,7 +144,7 @@ The possible paths of the status of PHEPs are as follows: "Accepted" PHEPs 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 PHEP. -Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main`. They mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. +Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the revision history). They mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. ## PHEP Maintenance From 9b0289461e96aa75a744e3c38dfe19830bcb72fb Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:43:09 -0500 Subject: [PATCH 49/84] phep-0001: implementation is unlikely for process pheps --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index a8a0b3d..84accb2 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -38,7 +38,7 @@ There are three types of PHEP: 2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. -3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. They may propose an implementation; they often require community consensus; unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. +3. A **Process** PHEP describes a process surrounding PyHC, or proposes a change to a process. Process PHEPs are like Standards Track PHEPs but apply to areas other than PyHC packages. Unlike Informational PHEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, and changes to the decision-making process. # PHEP Applicability From e2d5174062176ee6de2d54181d27f64019b2d99f Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:50:59 -0500 Subject: [PATCH 50/84] phep-0001: add quorum to open issues --- pheps/phep-0001.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 84accb2..931086d 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -319,6 +319,24 @@ A PHEP can be updated by introducing a new PHEP that starts with and builds on t ### Opposed Immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. +## Quorum requirement + +The [resolution process](#phep-review-resolution) does not require a quorum--in theory any properly-announced meeting could "vote" to accept a PHEP with a very small number of people present and potentially ram through a standard without consensus. Safeguards preventing this are: + +* Objections may be raised in the PR, so nobody need be present to break consensus for acceptance. +* There is a minimum one-month notice before the meeting allowing objections to be raised. +* Even if edits are made at the meeting, there is the period between the two votes for further objections, without edits being permitted. + +The word "vote" may be confusing here, as consensus is required, so any "nays" would carry. + +If the above safeguards are not evident in the [text](#phep-review-resolution), clarifying edits should be made. + +If a quorum requirement is deemed desirable, the following suggestions were made: + +* Requiring "substantial community representation" to be defined. +* Requiring representation from at least one core package. +* Requiring the author of the PHEP to at least be present to facilitate the discussion. This may be a reasonable requirement even if a quorum requirement is not defined. + # Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. It should be cited as: From 4dba25555f52959922570f8f6b7e4ef050b5c488 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:51:57 -0500 Subject: [PATCH 51/84] phep-0001: clarify 'Pythonic' --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 931086d..4b4a632 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -126,7 +126,7 @@ A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized "Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make the case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. -For a PHEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed change. The change must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. ("Pythonic" is an imprecise term; it may be defined as whatever is acceptable to the community. This logic is intentionally circular.) +For a PHEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed change. The change must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. ("Pythonic" is an imprecise term; it should be understood in the context of the broad Python ecosystem.) Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final" upon acceptance. From 9db6c891300a782c02e37c21927c634123c89a82 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:52:48 -0500 Subject: [PATCH 52/84] phep-0001: tag commit where phep is final --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 4b4a632..6a2d922 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -144,7 +144,7 @@ The possible paths of the status of PHEPs are as follows: "Accepted" PHEPs 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 PHEP. -Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the revision history). They mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. +Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the revision history). They tag the resulting commit and mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. ## PHEP Maintenance From 4ea9361f205f5784c128848e33365cb2865aae52 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:54:21 -0500 Subject: [PATCH 53/84] phep-0001: clarify what a standard is --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 6a2d922..8e5c065 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -34,7 +34,7 @@ This PHEP refers to "PyHC leadership": individuals or groups with statutory auth There are three types of PHEP: -1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. +1. A **Standards** Track PHEP describes a new or modified standard for PyHC packages. These standards are requirements that PyHC packages are expected to follow, similar to the original [PyHC standards](https://doi.org/10.5281/zenodo.2529131). Examples include testing requirements, OS support, and dependency handling. 2. An **Informational** PHEP describes a design issue, or provides general guidelines or information to the community, but does not propose a standard. Informational PHEPs do not necessarily represent a community recommendation, so users and implementers are free to ignore Informational PHEPs or follow their advice. From 0e2605ddc6a2411ede08f8b11138cf6f7568d436 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 13:56:59 -0500 Subject: [PATCH 54/84] phep-0001: Update the example preamble to match current text --- pheps/phep-0001.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 8e5c065..ae4258d 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -203,10 +203,10 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf ``` PHEP: Title: - Author: - Discussions-To: + Author: + Discussions-To: Status: + Withdrawn | Final | Replaced> Type: Content-Type: text/markdown; charset=UTF-8; variant=CommonMark * Requires: From 654f5643acf6fbba7c522da00655305851e5b8e5 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 14:05:25 -0500 Subject: [PATCH 55/84] phep-0001: impose requirement for accuracy on editors --- pheps/phep-0001.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index ae4258d..9028558 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -280,6 +280,8 @@ Once the PHEP is ready for discussion, a PHEP editor will: PHEP editors do not make judgments on the content or merits of PHEPs. They merely do the administrative & editorial part. They may participate in the community discussion of a PHEP but have no obligation to be advocates. +Once an author seeks [acceptance](#phep-review-resolution) of a PHEP, the editors should carefully review the existing wording to make sure it is clear, grammatically reasonable, and free of misspellings or other typos. + Disagreements with editors must be mediated by PyHC leadership (as documented in [PHEP audience](#phep-audience)) and they may impose sanctions, including removal of the editor role. # PHEP 1 Acceptance From e335aacd1346f0876f5a54d9d617bf3c11ec2e32 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Mon, 27 Nov 2023 14:06:03 -0500 Subject: [PATCH 56/84] phep-0001: new post history for new push --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 9028558..53f2a39 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -7,7 +7,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023 +Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023, 27-Nov-2023 ``` # What is a PHEP? From 340fb7e2eeda03d7b021f8c8f5837fea4c724db7 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 29 Nov 2023 09:38:47 -0500 Subject: [PATCH 57/84] phep-0001: fix riot link to element --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 53f2a39..7685567 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -66,7 +66,7 @@ The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on Git The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have an author: someone who writes the PHEP using the style and format described below, shepherds the discussion, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include a PyHC [telecon](https://heliopython.org/meetings/), the PyHC [mailing list](https://heliopython.org/contact/), PyHC [Matrix/Slack](https://riot.im/app/#/room/#heliopython:openastronomy.org), and [an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic. +Each PHEP must have an author: someone who writes the PHEP using the style and format described below, shepherds the discussion, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include a PyHC [telecon](https://heliopython.org/meetings/), the PyHC [mailing list](https://heliopython.org/contact/), PyHC [Matrix/Slack](https://app.element.io/#/room/#heliopython:openastronomy.org), and [an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic. Vetting an idea publicly before writing a PHEP is meant to save the author time. Asking the community first helps prevent too much time being spent on something that may 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. From 94d8d6be103b7ddbf18e2e877a1b77576c889e12 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Fri, 1 Dec 2023 16:20:22 -0500 Subject: [PATCH 58/84] phep-0001: remove the "accepted" state, go straight to final --- pheps/phep-0001.md | 21 +++++----- pheps/phep-0001/process_flow.svg | 69 +++++++------------------------- 2 files changed, 26 insertions(+), 64 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 7685567..d96b273 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -106,10 +106,12 @@ Standards Track PHEPs may consist of two parts, a design document and a referenc Once the draft PHEP is submitted in an open PR and a PHEP number has been assigned, the PR discussion thread provides the central place to discuss and review its contents. The PHEP must be updated so that the `Discussions-To` header links to the PR. The discussion must also be announced by the PHEP authors via reasonable means; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Matrix/Slack. -Informal conversation may happen elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Accepted". +Informal conversation may happen elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Final". PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. +If applicable, the reference implementation should be developed and tested as part of the discussion process. If changes are made based on implementation experience and user feedback, they should be noted in the PHEP. + PHEP authors are responsible for managing the progress of the discussion of their PHEP, for instance by updating the PR description to highlight topics of particular interest and to provide the dates of votes on the PHEP resolution. If a PHEP undergoes a significant re-write or other major changes, the author(s) and editor may discuss closing the existing PR and opening a new one, starting from the changed version. If this occurs, the `Discussions-To` link must be updated. @@ -126,9 +128,9 @@ A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized "Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make the case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. -For a PHEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed change. The change must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate PyHC projects unduly. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. ("Pythonic" is an imprecise term; it should be understood in the context of the broad Python ecosystem.) +For a PHEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed change. The change must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate PyHC projects unduly. If applicable, the reference implementation must be completed and incorporated into a PyHC project's source code repository. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. ("Pythonic" is an imprecise term; it should be understood in the context of the broad Python ecosystem.) -Once a PHEP has been accepted, the reference implementation, if applicable, must be completed. When the reference implementation is complete and incorporated into a PyHC project's source code repository, the status will be changed to "Final". PHEPs which do not require a reference implementation move immediately to "Final" upon acceptance. +Once a PHEP has been accepted, its status will be changed to "Final". If no progress is being made on the PHEP, the editor should consult the author. The author may resume work on the PHEP, [transfer it to another author](transferring-phep-ownership), or withdraw it. If the author takes none of these actions, the editor may choose to bring the PHEP to the community for acceptance or rejection in its current form. @@ -142,16 +144,12 @@ The possible paths of the status of PHEPs are as follows: ![PHEP status flow diagram](phep-0001/process_flow.svg) -"Accepted" PHEPs 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 PHEP. - Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the revision history). They tag the resulting commit and mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. ## PHEP Maintenance PHEPs are no longer substantially modified after they have left the Draft state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. -If changes based on implementation experience and user feedback are made to PHEPs while in the Accepted state, they should be noted in the PHEP, such that the PHEP accurately describes the implementation at the point where it is marked Final. - Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. Changes to PHEPs in the Final state are limited to the preamble, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. @@ -205,8 +203,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Title: Author: Discussions-To: - Status: + Status: Type: Content-Type: text/markdown; charset=UTF-8; variant=CommonMark * Requires: @@ -295,6 +292,12 @@ PHEP 1 is based on [PEP 1](https://peps.python.org/pep-0001/), which is a proces # Rejected Ideas +## Acceptance without reference implementation + +In contrast to PEP 1, any reference implementation must be complete before a PHEP is brought to a vote: there is no "Accepted" state between Draft and Final. This simplifies flow and avoids defining a process for moving from Accepted to Final, particularly if the implementation results in changes. + +Effort may go into a reference implementation for a standard that then gets voted down, or requires major changes to be accepted. This can be avoided by getting substantial input before starting the reference implementation and allowing the standard and implementation to evolve together. Implementation is also likely to be smaller effort (relative to the standard) for PyHC than for the Python language. + ## ASCII encoding As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. diff --git a/pheps/phep-0001/process_flow.svg b/pheps/phep-0001/process_flow.svg index e1f8ec3..34a42ec 100644 --- a/pheps/phep-0001/process_flow.svg +++ b/pheps/phep-0001/process_flow.svg @@ -7,7 +7,7 @@ preserveAspectRatio="xMidYMid meet" id="svg3789" sodipodi:docname="process_flow.svg" - inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)" + inkscape:version="1.2.2 (b0a8486541, 2022-12-01)" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns="http://www.w3.org/2000/svg" @@ -57,21 +57,6 @@ d="M 0,0 5,-5 -12.5,0 5,5 Z" id="path15175" /> - - - + fit-margin-bottom="10" + inkscape:showpageshadow="2" + inkscape:deskcolor="#d1d1d1"> + transform="translate(-179.32069,-0.43747711)"> Final - - - Accepted - + transform="translate(-2.3349497,-80.137138)"> @@ -313,12 +278,6 @@ id="path12305" inkscape:connector-curvature="0" sodipodi:nodetypes="cc" /> - Date: Fri, 1 Dec 2023 16:22:32 -0500 Subject: [PATCH 59/84] phep-0001: declare immutability resolved --- pheps/phep-0001.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index d96b273..eee2000 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -302,6 +302,14 @@ Effort may go into a reference implementation for a standard that then gets vote As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. +## Mutability of PHEPs + +PHEPs are [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This maintains clarity of reference, "PHEP-x" rather than "PHEP-x version y", and avoids confusion arising from rolling updates. It encourages getting the PHEP correct before first acceptance. Finally, it removes the need to define and document an update process. + +A PHEP can be updated by introducing a new PHEP that starts with and builds on the original text. Everything is then open for discussion. This encourages complete re-evaluation if the community reaches the point where something is important enough to revisit, and discourages fixing a typo that doesn't hurt anything. + +On the downside, immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. + ## Recording names at acceptance There was consideration of recording the names of people present when a PHEP is accepted, or who specifically want to "sign on". This was decided to be out-of-scope for the PHEP process; the notes of the meeting should capture relevant information. @@ -312,17 +320,6 @@ Certain ideas regarding the format of the Markdown source were removed as more c # Open Issues -## Immutability of PHEPs - -PHEPs are proposed to be [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This is not universally accepted. - -### In favor -Immutability maintains clarity of reference, "PHEP-x" rather than "PHEP-x version y", and avoids confusion arising from rolling updates. It encourages getting the PHEP correct before first acceptance. Finally, it removes the need to define and document an update process. - -A PHEP can be updated by introducing a new PHEP that starts with and builds on the original text. Everything is then open for discussion. This encourages complete re-evaluation if the community reaches the point where something is important enough to revisit, and discourages fixing a typo that doesn't hurt anything. - -### Opposed -Immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. ## Quorum requirement From 9ffbfb15e8c3e72482945c5b282cca95938b885f Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Fri, 1 Dec 2023 16:28:14 -0500 Subject: [PATCH 60/84] phep-0001: declare quorum issue resolved --- pheps/phep-0001.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index eee2000..009d976 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -310,6 +310,22 @@ A PHEP can be updated by introducing a new PHEP that starts with and builds on t On the downside, immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. +## Quorum requirement + +The [resolution process](#phep-review-resolution) does not require a quorum for a vote. Suggested quorum requirements included: + +* Requiring "substantial community representation" at a vote. +* Requiring representation from at least one core package at a vote. +* Requiring the author of the PHEP to at least be present for the vote. + +In theory any properly-announced meeting could "vote" to accept a PHEP with a very small number of people present and potentially ram through a standard without community consensus. Safeguards preventing this are: + +* Objections may be raised in the PR, so nobody need be present to break consensus for acceptance. +* The minimum one-month notice before the meeting allows objections to be raised. +* If edits are made at the meeting before the vote, the the period between the two votes does not permit edits and allows for further objections. + +As consensus is required, any of these "nays" carry the vote. + ## Recording names at acceptance There was consideration of recording the names of people present when a PHEP is accepted, or who specifically want to "sign on". This was decided to be out-of-scope for the PHEP process; the notes of the meeting should capture relevant information. @@ -321,23 +337,7 @@ Certain ideas regarding the format of the Markdown source were removed as more c # Open Issues -## Quorum requirement - -The [resolution process](#phep-review-resolution) does not require a quorum--in theory any properly-announced meeting could "vote" to accept a PHEP with a very small number of people present and potentially ram through a standard without consensus. Safeguards preventing this are: - -* Objections may be raised in the PR, so nobody need be present to break consensus for acceptance. -* There is a minimum one-month notice before the meeting allowing objections to be raised. -* Even if edits are made at the meeting, there is the period between the two votes for further objections, without edits being permitted. - -The word "vote" may be confusing here, as consensus is required, so any "nays" would carry. - -If the above safeguards are not evident in the [text](#phep-review-resolution), clarifying edits should be made. - -If a quorum requirement is deemed desirable, the following suggestions were made: - -* Requiring "substantial community representation" to be defined. -* Requiring representation from at least one core package. -* Requiring the author of the PHEP to at least be present to facilitate the discussion. This may be a reasonable requirement even if a quorum requirement is not defined. +There are no remaining open issues. # Copyright From a7c527e3d458f755ba3469347396d31b80b1d241 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 6 Dec 2023 17:51:13 -0500 Subject: [PATCH 61/84] phep-0001: workflow diagram --- pheps/phep-0001.md | 6 + pheps/phep-0001/workflow.dot | 112 +++++++++++++++ pheps/phep-0001/workflow.svg | 269 +++++++++++++++++++++++++++++++++++ 3 files changed, 387 insertions(+) create mode 100644 pheps/phep-0001/workflow.dot create mode 100644 pheps/phep-0001/workflow.svg diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 009d976..3a38abe 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -146,6 +146,12 @@ The possible paths of the status of PHEPs are as follows: Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the revision history). They tag the resulting commit and mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. +The complete PHEP approval process is: + +![PHEP workflow diagram](phep-0001/workflow.svg) + +The author may withdraw the PHEP at any time, so this is not shown. Replacement of a PHEP is not shown as it results from the approval of a new, replacement PHEP using the same process. + ## PHEP Maintenance PHEPs are no longer substantially modified after they have left the Draft state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. diff --git a/pheps/phep-0001/workflow.dot b/pheps/phep-0001/workflow.dot new file mode 100644 index 0000000..ab6ad98 --- /dev/null +++ b/pheps/phep-0001/workflow.dot @@ -0,0 +1,112 @@ +// dot -Tsvg workflow.dot -o workflow.svg +digraph g { +graph [ rankdir="TB" ]; +bgcolor=transparent; +splines=true; +node [shape=box group=main]; +layout=dot; + +author_discussion [ + label="Author opens discussion / issue" +] + +author_draft [ + label="Author drafts PHEP" +] +author_discussion -> author_draft + +author_pr [ + label="Author opens draft PR" +] +author_draft -> author_pr + +editor_review [ + label="Editor reviews.\nFormat\ncompliant?" + shape=diamond +] +author_pr -> editor_review + +editor_assigns [ + label="Editor assigns number" +] +editor_review -> editor_assigns [label="Yes"] + +author_updates_number [ + label="Author updates\nPR link, number, date created, posted\nMarks PR ready for review" +] +editor_assigns -> author_updates_number + +discussion [ + label="Discussion, revision,\nreference implementation" +] +author_updates_number -> discussion + +vote1_announced [ + label="First vote announced" +] +discussion -> vote1_announced + +further_discussion [ + label="Futher discussion / edits" +] +vote1_announced -> further_discussion + +vote1 [ + label="First\nvote" + shape=diamond +] +further_discussion -> vote1 + +result1 [ + label="Result announced" +] +edited -> vote1 [taillabel="Y" constraint=False] +vote1 -> result1 [taillabel="Consensus"] + +vote2_announced [ + label="Second vote announced" +] +result1 -> vote2_announced + +edited [ + label="Edited since\nfirst vote?" + shape=diamond +] +vote2_announced -> edited + +vote2 [ + label="Second\nvote" + shape=diamond +] +edited -> vote2 [taillabel="N"] + +final [ + label="Mark Final, update Resolution, merge" +] +vote2 -> final [taillabel="Consensus"] + +return_for_revision [ + label="Editor returns to\nauthor for revision" + group=right +] +editor_review -> return_for_revision [label="No"] +return_for_revision -> editor_review [constraint=False headport=e] + +author_continues [ + label="Author\ncontinues\nto edit?" + shape=diamond + group=right +] +vote1 -> author_continues [label="No consensus" constraint=False] +author_continues -> discussion [taillabel="Y" constraint=False tailport=n headport=e] +vote2 -> author_continues [taillabel="No consensus" constraint=False headport=s tailport=e] + +rejected [ + label="Rejected" + group=right +] +author_continues -> rejected [taillabel="N" constraint=False] + +further_discussion -> author_continues [style="invis"] +further_discussion -> rejected [style="invis"] +} \ No newline at end of file diff --git a/pheps/phep-0001/workflow.svg b/pheps/phep-0001/workflow.svg new file mode 100644 index 0000000..48e2e4b --- /dev/null +++ b/pheps/phep-0001/workflow.svg @@ -0,0 +1,269 @@ + + + + + + +g + + +author_discussion + +Author opens discussion / issue + + + +author_draft + +Author drafts PHEP + + + +author_discussion->author_draft + + + + + +author_pr + +Author opens draft PR + + + +author_draft->author_pr + + + + + +editor_review + +Editor reviews. +Format +compliant? + + + +author_pr->editor_review + + + + + +editor_assigns + +Editor assigns number + + + +editor_review->editor_assigns + + +Yes + + + +return_for_revision + +Editor returns to +author for revision + + + +editor_review->return_for_revision + + +No + + + +author_updates_number + +Author updates +PR link, number, date created, posted +Marks PR ready for review + + + +editor_assigns->author_updates_number + + + + + +discussion + +Discussion, revision, +reference implementation + + + +author_updates_number->discussion + + + + + +vote1_announced + +First vote announced + + + +discussion->vote1_announced + + + + + +further_discussion + +Futher discussion / edits + + + +vote1_announced->further_discussion + + + + + +vote1 + +First +vote + + + +further_discussion->vote1 + + + + + +author_continues + +Author +continues +to edit? + + + + +rejected + +Rejected + + + + +result1 + +Result announced + + + +vote1->result1 + + +Consensus + + + +vote1->author_continues + + +No consensus + + + +vote2_announced + +Second vote announced + + + +result1->vote2_announced + + + + + +edited + +Edited since +first vote? + + + +edited->vote1 + + +Y + + + +vote2 + +Second +vote + + + +edited->vote2 + + +N + + + +vote2_announced->edited + + + + + +final + +Mark Final, update Resolution, merge + + + +vote2->final + + +Consensus + + + +vote2:e->author_continues:s + + +No consensus + + + +return_for_revision->editor_review:e + + + + + +author_continues:n->discussion:e + + +Y + + + +author_continues->rejected + + +N + + + From 1c570d6c98981fb21b79af2627c4bf6c7605672a Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 6 Dec 2023 17:52:24 -0500 Subject: [PATCH 62/84] phep-0001: clarify can force-push before opening for review --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 3a38abe..0c3392d 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -108,7 +108,7 @@ Once the draft PHEP is submitted in an open PR and a PHEP number has been assign Informal conversation may happen elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Final". -PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. PHEP authors must not rewrite history after a push, i.e. no force-pushing. +PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. Once a PHEP PR has been marked ready for review, PHEP authors must not rewrite history after a push, i.e. no force-pushing. If applicable, the reference implementation should be developed and tested as part of the discussion process. If changes are made based on implementation experience and user feedback, they should be noted in the PHEP. From 631e19b70285a783e0d769fbd5f85abb9e3e924c Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 6 Dec 2023 17:52:59 -0500 Subject: [PATCH 63/84] phep-0001: new post history for new push --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 0c3392d..a5c6855 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -7,7 +7,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023, 27-Nov-2023 +Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023, 27-Nov-2023, 06-Dec-2023 ``` # What is a PHEP? From 0242c0f54d51bdb24c5855abda8196cb3f1e23ab Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 14 Dec 2023 18:01:11 -0500 Subject: [PATCH 64/84] phep-0001: link the contact page, not element directly --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index a5c6855..d35f856 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -66,7 +66,7 @@ The editors can be contacted by mentioning `@heliophysicsPy/phep-editors` on Git The PHEP process begins with a new idea for PyHC. It is highly recommended that a single PHEP contain a single key proposal or new idea; the more focused the PHEP, the more successful it tends to be. If in doubt, split your PHEP into several well-focused ones. -Each PHEP must have an author: someone who writes the PHEP using the style and format described below, shepherds the discussion, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include a PyHC [telecon](https://heliopython.org/meetings/), the PyHC [mailing list](https://heliopython.org/contact/), PyHC [Matrix/Slack](https://app.element.io/#/room/#heliopython:openastronomy.org), and [an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic. +Each PHEP must have an author: someone who writes the PHEP using the style and format described below, shepherds the discussion, and attempts to build community consensus around the idea. The PHEP author should first attempt to ascertain whether the idea is PHEP-able. Suggested venues for this discussion include a PyHC [telecon](https://heliopython.org/meetings/), other established PyHC [discussion channels](https://heliopython.org/contact/) including the email list or Matrix/Slack, and [an issue in the standards repository](https://github.com/heliophysicsPy/standards/issues/new/choose) (which should be linked to the PR when the PHEP is submitted). The author may choose the approach that seems best for their topic. Vetting an idea publicly before writing a PHEP is meant to save the author time. Asking the community first helps prevent too much time being spent on something that may 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. From f2f43388df5eab3af4895c9400d5beddf8fbae87 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 14 Dec 2023 18:04:34 -0500 Subject: [PATCH 65/84] phep-0001: PHEPs define their own applicability --- pheps/phep-0001.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index d35f856..e97a97b 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -48,6 +48,8 @@ There are three types of PHEP: **Process** PHEPs determine the process by which the PyHC community makes formal decisions and as such bind all participants in PyHC. +A PHEP may provide further guidance on its applicability and implementation (e.g. timelines for compliance). PHEPs that define the applicability of other PHEPs are usually Process PHEPs. + For all three types, key words in PHEPs must be interpreted according to [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119); the use of `must`, `must not`, `should`, and `should not` are preferred. # PHEP Workflow From 50d1e696493a8c92631af0c34fafe9b35e8bac89 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 14 Dec 2023 18:06:17 -0500 Subject: [PATCH 66/84] phep-0001: remove reference to 'philosophy' --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index e97a97b..ba603f7 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -100,7 +100,7 @@ The standard PHEP workflow is: * Once approved, they will assign your PHEP a number. All PHEPs are sequentially-numbered at time of assignment. "Special" numbers (X, 0, etc.) are not used. Upon approval, the author must mark the PHEP PR ready for review. -The PHEP editors will not unreasonably deny approval of a PHEP. Reasons for denying PHEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the PyHC philosophy. +The PHEP editors will not unreasonably deny approval of a PHEP. Reasons for denying PHEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or so incompatible with PyHC practice as to be infeasible. Standards Track PHEPs may consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation in an existing or new PyHC package be co-developed with the PHEP, as ideas that sound good in principle sometimes turn out to be impractical when implemented. From b039979a8b8bbdc2d2613ffaf06ee294a72dd2c1 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 14 Dec 2023 18:07:22 -0500 Subject: [PATCH 67/84] phep-0001: clarify significance of GH reviews --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index ba603f7..d05ede5 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -108,7 +108,7 @@ Standards Track PHEPs may consist of two parts, a design document and a referenc Once the draft PHEP is submitted in an open PR and a PHEP number has been assigned, the PR discussion thread provides the central place to discuss and review its contents. The PHEP must be updated so that the `Discussions-To` header links to the PR. The discussion must also be announced by the PHEP authors via reasonable means; this includes (but is not necessarily limited to) the PyHC email list and the PyHC Matrix/Slack. -Informal conversation may happen elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they believe the PHEP is ready for a vote; however, this does not change the PHEP status to "Final". +Informal conversation may happen elsewhere, but the discussion of record is the public thread on the pull request. Substantive input into the PHEP or questions about it belong in the PR comments and side conversations should result in comments on the PR. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure input is fully considered as part of the PHEP review process. Feedback on the PR thread is a critical part of what the community will consider when reviewing the PHEP. Individual comments or the GitHub "review" process may both be used. Commenters may use the GitHub "approve" feedback to indicate they support the PHEP; however, this does not change the PHEP status to "Final". PHEP authors should incorporate community feedback by making edits and additional pushes to their branch. They must add a new `Post-History` entry with each push. It is recommended to address as much actionable feedback as practicable with each push; however, each push may contain multiple commits for ease of review. Once a PHEP PR has been marked ready for review, PHEP authors must not rewrite history after a push, i.e. no force-pushing. From 2405abddc3af0ee2dfefb791e4131ed165e42dc8 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 14 Dec 2023 18:09:44 -0500 Subject: [PATCH 68/84] phep-0001: clarify first step of workflow diagram --- pheps/phep-0001/workflow.dot | 2 +- pheps/phep-0001/workflow.svg | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pheps/phep-0001/workflow.dot b/pheps/phep-0001/workflow.dot index ab6ad98..851457d 100644 --- a/pheps/phep-0001/workflow.dot +++ b/pheps/phep-0001/workflow.dot @@ -7,7 +7,7 @@ node [shape=box group=main]; layout=dot; author_discussion [ - label="Author opens discussion / issue" + label="Author gathers community input" ] author_draft [ diff --git a/pheps/phep-0001/workflow.svg b/pheps/phep-0001/workflow.svg index 48e2e4b..897271f 100644 --- a/pheps/phep-0001/workflow.svg +++ b/pheps/phep-0001/workflow.svg @@ -11,8 +11,8 @@ author_discussion - -Author opens discussion / issue + +Author gathers community input From 68125caadd7c081ecc8fc9f803c6d3ebebebce58 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 14 Dec 2023 18:10:54 -0500 Subject: [PATCH 69/84] phep-0001: new post history for new push --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index d05ede5..51e2e8b 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -7,7 +7,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023, 27-Nov-2023, 06-Dec-2023 +Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023 ``` # What is a PHEP? From 011c6f19c0c963de93320286965bc5a652165347 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 11:05:13 -0500 Subject: [PATCH 70/84] phep-0001: recommendation that author be present for vote --- pheps/phep-0001.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 51e2e8b..27338ae 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -128,7 +128,7 @@ A PHEP is accepted by consensus of attendees (virtual or in-person) at both a Py A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. -"Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make the case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. +"Consensus" here means no concrete objections have been raised: an accepted PHEP must be one that the entire community can at least live with. The PHEP authors must make the case for the PHEP; objectors must provide meaningful concerns that could, in principle, be addressed by the authors. All are expected to discuss in good faith, while recognizing that good faith does not guarantee consensus can be reached. The author of a PHEP should be present for the vote on the PHEP so they can contribute to any discussion and answer questions. If they are not able to make the meeting, they should designate an alternate who can speak effectively for them. For a PHEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed change. The change must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate PyHC projects unduly. If applicable, the reference implementation must be completed and incorporated into a PyHC project's source code repository. Finally, a proposed enhancement must be "pythonic" in order to be accepted by the community. ("Pythonic" is an imprecise term; it should be understood in the context of the broad Python ecosystem.) @@ -324,7 +324,6 @@ The [resolution process](#phep-review-resolution) does not require a quorum for * Requiring "substantial community representation" at a vote. * Requiring representation from at least one core package at a vote. -* Requiring the author of the PHEP to at least be present for the vote. In theory any properly-announced meeting could "vote" to accept a PHEP with a very small number of people present and potentially ram through a standard without community consensus. Safeguards preventing this are: @@ -334,6 +333,8 @@ In theory any properly-announced meeting could "vote" to accept a PHEP with a ve As consensus is required, any of these "nays" carry the vote. +The recommendation that the author of the PHEP be present for the [vote](#phep-review-resolution) came out of quorum discussions. + ## Recording names at acceptance There was consideration of recording the names of people present when a PHEP is accepted, or who specifically want to "sign on". This was decided to be out-of-scope for the PHEP process; the notes of the meeting should capture relevant information. From 319bdedc272726d956cc44058c30a15fd9d1f991 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 11:06:38 -0500 Subject: [PATCH 71/84] phep-0001: add the changes requirement to the how-to-teach --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 27338ae..49eac5c 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -182,7 +182,7 @@ Each PHEP should have the following elements, where they are applicable. It is s 7. **Security Implications** - Any security concerns should be explicitly written out. -8. **How to Teach This** - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work. +8. **How to Teach This** - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work. This section should also document any changes the PHEP makes relative to a PHEP it replaces or some other widely-used standard or reference. This allows an implementation compliant with a previous PHEP (or other standard) to be easily updated for compliance with the PHEP. 9. **Reference Implementation** - The reference implementation must be completed before any PHEP is given status "Final", but it need not be completed before the PHEP 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. From b0c21085d509416bf96b32222e45d9c083ad24ac Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 11:16:23 -0500 Subject: [PATCH 72/84] phep-0001: Remove link to discussion thread from Post-History header * The Discussions-To link should fulfil this requirement. * Note that old thread should be linked if a new PR is opened. --- pheps/phep-0001.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 49eac5c..e686fe0 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -116,7 +116,7 @@ If applicable, the reference implementation should be developed and tested as pa PHEP authors are responsible for managing the progress of the discussion of their PHEP, for instance by updating the PR description to highlight topics of particular interest and to provide the dates of votes on the PHEP resolution. -If a PHEP undergoes a significant re-write or other major changes, the author(s) and editor may discuss closing the existing PR and opening a new one, starting from the changed version. If this occurs, the `Discussions-To` link must be updated. +If a PHEP undergoes a significant re-write or other major changes, the author(s) and editor may discuss closing the existing PR and opening a new one, starting from the changed version. If this occurs, the `Discussions-To` link must be updated, and the new PR discussion should link to the old for reference. PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.org/docs/code_of_conduct/). @@ -216,8 +216,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Content-Type: text/markdown; charset=UTF-8; variant=CommonMark * Requires: Created: - Post-History: + Post-History: * Replaces: * Replaced-By: * Resolution: From d75c990dd832542fa4899b004c8796f47677eb33 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 11:20:05 -0500 Subject: [PATCH 73/84] phep-0001: explicitly require announcement of second vote be after first --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index e686fe0..a589197 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -124,7 +124,7 @@ PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.o Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is the responsibility of the community. It should be clear from the [discussion](#discussing-a-phep) when the community is beginning to agree: concerns have been addressed and new ones are not being raised, PR reviews with "approve" status are appearing, discussion is quieting down. At this point the PHEP author should seek formal acceptance. -A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, with no edits to the PHEP occurring in between. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. Persons not in attendance at the meetings may object via comment on the PR. The PHEP may be edited up until the initial vote, for instance to incorporate discussion at the meeting. However, any edits after a vote invalidate that acceptance, and two further votes (one at a meeting, one on a telecon) must be taken. +A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, with no edits to the PHEP occurring in between. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. The formal announcement of a vote must take place *after* the previous vote, effectively requiring a month between votes. Persons not in attendance at the meetings may object via comment on the PR. The PHEP may be edited up until the initial vote, for instance to incorporate discussion at the meeting. However, any edits after a vote invalidate that acceptance, and two further votes (one at a meeting, one on a telecon) must be taken. A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. From f1092a0b990aa0ad140b9a1117e123aa54a6e717 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 11:36:19 -0500 Subject: [PATCH 74/84] phep-0001: notes on flexibility of standards --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index a589197..57d415a 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -160,7 +160,7 @@ PHEPs are no longer substantially modified after they have left the Draft state. Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. -Changes to PHEPs in the Final state are limited to the preamble, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. +Changes to PHEPs in the Final state are limited to the preamble, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. A PHEP should also be written to be appropriately flexible to changes in technical details that do not affect the core purpose of the PHEP, e.g. specific URI's. The division of details between the PHEP and the reference implementation should be chosen carefully. Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. # What belongs in a successful PHEP? From 6d15f0dc10fa7cb8e6dacb46f8a3c9b0554cf1ac Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 12:22:58 -0500 Subject: [PATCH 75/84] phep-0001.md: introduce revision process * Includes rewriting to make sure 'revise' refers only to this process --- pheps/phep-0001.md | 67 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 52 insertions(+), 15 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 57d415a..fed409a 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -3,6 +3,7 @@ PHEP: 1 Title: PHEP Purpose and Guidelines Author: Jonathan T. Niehof Discussions-To: https://github.com/heliophysicsPy/standards/pull/22 +Revision: 1 Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark @@ -16,7 +17,7 @@ PHEP stands for PyHC Enhancement Proposal. A PHEP provides information to the Py PHEPs are the primary mechanism for proposing standards, collecting community input, and documenting the design decisions underlying PyHC standards and recommendations. The PHEP process develops and documents consensus within the community. The PHEP author is responsible for building this consensus and documenting dissenting opinions. -Because PHEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This record is available by the normal git commands for retrieving older revisions and can be browsed [on GitHub](https://github.com/heliophysicsPy/standards). +Because PHEPs are maintained as text files in a versioned repository, their commit history is the historical record of the feature proposal. This record is available by the normal git commands for retrieving older commits and can be browsed [on GitHub](https://github.com/heliophysicsPy/standards). # PHEP Motivation @@ -138,7 +139,7 @@ If no progress is being made on the PHEP, the editor should consult the author. If a PHEP fails to find consensus, the author may choose to modify it for reconsideration. The PHEP may be "Withdrawn" if the PHEP author themself decides that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. -When a PHEP changes state, the PHEP preamble must be updated accordingly. In addition to updating the Status field, the Resolution header must be added with a direct link to the minutes of the telecons and meetings where a decision on the PHEP was made. The editors must post announcements of PHEP resolution to the PyHC mailing list. +When a PHEP changes state, the PHEP preamble must be updated accordingly. In addition to updating the Status field, the Resolution header must be added with a direct link to the minutes of the telecons and meetings where a decision on the PHEP was made. The Revision section must be updated with the data of acceptance, as appropriate. The editors must post announcements of PHEP resolution to the PyHC mailing list. Final PHEPs can also be replaced by a different PHEP, rendering the original obsolete. @@ -146,7 +147,7 @@ The possible paths of the status of PHEPs are as follows: ![PHEP status flow diagram](phep-0001/process_flow.svg) -Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the revision history). They tag the resulting commit and mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. +Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the commit history). They tag the resulting commit and mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. The complete PHEP approval process is: @@ -160,7 +161,26 @@ PHEPs are no longer substantially modified after they have left the Draft state. Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. -Changes to PHEPs in the Final state are limited to the preamble, and only in the event the PHEP is replaced. Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. A PHEP should also be written to be appropriately flexible to changes in technical details that do not affect the core purpose of the PHEP, e.g. specific URI's. The division of details between the PHEP and the reference implementation should be chosen carefully. Preamble changes are made via PR to the `standards` repository, merged by PHEP editors. +Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. A PHEP should also be written to be appropriately flexible to changes in technical details that do not affect the core purpose of the PHEP, e.g. specific URI's. The division of details between the PHEP and the reference implementation should be chosen carefully. + +A Final PHEP can be revised to accommodate changes that do not change its substance. The permissible scope can be described as changes that would reflect a "patch" or "subminor" version change in semantic versioning schemes; examples include: + +1. A PHEP is Replaced due to acceptance of a new PHEP, requiring an update to the header. +2. A clear typo, misspelling, or other error not affecting the meaning of a PHEP is found. +3. A URI or similar external reference is moved / updated. + +A revision can be made by the PHEP editors or by the author; if the editors intend to make a revision, they should consult the original author. + +To revise a PHEP, a PR must be opened with the following changes to the PHEP: + +1. The Revision header is incremented by one. +2. The Status is updated to Replaced and the Replaced-By header updated if a PHEP has been replaced. +3. The Post-History header is updated with the date of the new PR. +4. A new entry is added in the Revisions section, briefly explaining the changes and the need for them. +5. The copyright date is updated as necessary. +6. A new DOI is reserved and the DOI updated in the citation. + +These changes must be made in a single commit, which the editors can merge after minor discussion. This PR should not be opened until the path forward is clear: this process is for incremental, non-controversial revisions. Once merged, the commit is tagged. A DOI is minted and marked as new version of the previous DOI. # What belongs in a successful PHEP? @@ -194,7 +214,9 @@ Each PHEP should have the following elements, where they are applicable. It is s 12. **Footnotes** - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. -13. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) and include citation information (see this PHEP for an example). +13. **Revisions** - Brief summary of changes by revision number, including the date of approval. + +14. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) and include citation information (see this PHEP for an example). # PHEP Formats and Templates @@ -211,6 +233,7 @@ Each PHEP must begin with an [RFC 2822](https://datatracker.ietf.org/doc/html/rf Title: Author: Discussions-To: + Revision: Status: Type: Content-Type: text/markdown; charset=UTF-8; variant=CommonMark @@ -236,6 +259,8 @@ If there are multiple authors, each should be on a separate line following [RFC The Discussions-To header provides the URL to the current PR discussion thread for the PHEP. +The Revision header is an integer, starting at 1, indicating the revision of the PHEP. This is only incremented when a Final PHEP is revised; see [PHEP maintenance](phep-maintenance) for details. + The Type header specifies the [type](#phep-type) of PHEP: Standards Track, Informational, or Process. The format of a PHEP is specified with a Content-Type header. All PHEPs must use Markdown, and have a value of `text/markdown; charset=UTF-8; variant=CommonMark`. @@ -274,7 +299,7 @@ For each new PHEP that comes in, an editor does the following: * If a project is portrayed as benefiting from or supporting the PHEP, make sure there is some direct indication from the project included to make the support clear. -If the PHEP isn't ready, an editor will send it back to the author for revision, with specific instructions. +If the PHEP isn't ready, an editor will send it back to the author for updates, with specific instructions. Once the PHEP is ready for discussion, a PHEP editor will: @@ -309,14 +334,6 @@ Effort may go into a reference implementation for a standard that then gets vote As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. -## Mutability of PHEPs - -PHEPs are [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This maintains clarity of reference, "PHEP-x" rather than "PHEP-x version y", and avoids confusion arising from rolling updates. It encourages getting the PHEP correct before first acceptance. Finally, it removes the need to define and document an update process. - -A PHEP can be updated by introducing a new PHEP that starts with and builds on the original text. Everything is then open for discussion. This encourages complete re-evaluation if the community reaches the point where something is important enough to revisit, and discourages fixing a typo that doesn't hurt anything. - -On the downside, immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. - ## Quorum requirement The [resolution process](#phep-review-resolution) does not require a quorum for a vote. Suggested quorum requirements included: @@ -345,7 +362,27 @@ Certain ideas regarding the format of the Markdown source were removed as more c # Open Issues -There are no remaining open issues. +## Mutability of PHEPs + +As currently written, PHEPs are [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This maintains clarity of reference, "PHEP-x" rather than "PHEP-x version y", and avoids confusion arising from rolling updates. It encourages getting the PHEP correct before first acceptance. Finally, it removes the need to define and document an update process. + +A PHEP can be updated by introducing a new PHEP that starts with and builds on the original text. Everything is then open for discussion. This encourages complete re-evaluation if the community reaches the point where something is important enough to revisit. + +On the downside, immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. + +From the immutability discussion, a process was introduced for making very small changes, such as fixing typos. + +The possible approaches that emerged from discussion roughly span the range: + +1. Pure immutability, a PHEP cannot be changed after it is Final. This has conceptually the simplest process (fewest possible steps, headers etc.) but is inflexible. +2. Allowing non-substantive changes to be undertaken without community review; PHEP-1 is currently written to this standard. +3. Further allowing some level of substantive change with potentially more streamlined review, without drafting a new PHEP. This is perhaps the most flexible approach. + +One of the reasons for minimizing streamlined changes is the lack of a central decision-making authority; there is, at this writing, no PyHC steering committee or similar, that can assume responsibility for approvals in the absence of community consensus. A future PHEP can be introduced replacing PHEP-1 to provide for a broader revision process. + +# Revisions + +Revision 1 (pending): Initial approval. # Copyright From d61c24259f8f6970b65e7a4f36b038dca12aa20d Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 12:43:35 -0500 Subject: [PATCH 76/84] phep-0001: readdown and tweak for clarity --- pheps/phep-0001.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index fed409a..c89c126 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -49,7 +49,7 @@ There are three types of PHEP: **Process** PHEPs determine the process by which the PyHC community makes formal decisions and as such bind all participants in PyHC. -A PHEP may provide further guidance on its applicability and implementation (e.g. timelines for compliance). PHEPs that define the applicability of other PHEPs are usually Process PHEPs. +A PHEP may provide further guidance on its applicability and implementation (e.g. timelines for compliance). PHEPs may define the applicability of other PHEPs; these are usually Process PHEPs. For all three types, key words in PHEPs must be interpreted according to [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119); the use of `must`, `must not`, `should`, and `should not` are preferred. @@ -125,7 +125,7 @@ PHEP discussions are subject to the [PyHC Code of Conduct](https://heliopython.o Once the authors have completed a PHEP, they may request a review for style and consistency from the PHEP editors. However, content review and acceptance of the PHEP is the responsibility of the community. It should be clear from the [discussion](#discussing-a-phep) when the community is beginning to agree: concerns have been addressed and new ones are not being raised, PR reviews with "approve" status are appearing, discussion is quieting down. At this point the PHEP author should seek formal acceptance. -A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, with no edits to the PHEP occurring in between. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. The formal announcement of a vote must take place *after* the previous vote, effectively requiring a month between votes. Persons not in attendance at the meetings may object via comment on the PR. The PHEP may be edited up until the initial vote, for instance to incorporate discussion at the meeting. However, any edits after a vote invalidate that acceptance, and two further votes (one at a meeting, one on a telecon) must be taken. +A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, in either order, with no edits to the PHEP occurring in between. Potential acceptance of a PHEP must be placed on the agenda at least a month before the meeting, including a link to the open PR with the proposed-final language of the PHEP. The formal announcement of a vote must take place *after* the previous vote, effectively requiring a month between votes. Persons not in attendance at the meetings may object via comment on the PR. The PHEP may be edited up until the initial vote, for instance to incorporate discussion at the meeting. However, any edits after a vote invalidate that acceptance, and two further votes (one at a meeting, one on a telecon) must be taken. A "regular PyHC meeting" is any meeting (virtual, physical, or hybrid) organized for the purpose of discussing PyHC business, of at least a half-day duration, where a substantial portion of the community is expected to participate, and announced as such well in advance. This includes the semiannual meetings but may also include side gatherings at other meetings which are of interest to the community and designated as PyHC meetings. @@ -147,7 +147,15 @@ The possible paths of the status of PHEPs are as follows: ![PHEP status flow diagram](phep-0001/process_flow.svg) -Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors update the preamble and merge the PR into `main` (maintaining the commit history). They tag the resulting commit and mint a DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated. +Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors or author push a commit to the PR branch which: + +1. Updates the Status appropriately. +2. Puts the current date in the Post-History header. +3. Updates the Revisions section with the date accepted or rejected, as appropriate. +4. Updates the copyright date as necessary. +6. Updates the DOI in the citation with a new DOI that the editors have reserved + +The editors merge the PR into `main` (maintaining the commit history). They tag the resulting commit and mint the reserved DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated (see [PHEP Maintenance](#phep-maintenance)). The complete PHEP approval process is: @@ -157,11 +165,11 @@ The author may withdraw the PHEP at any time, so this is not shown. Replacement ## PHEP Maintenance -PHEPs are no longer substantially modified after they have left the Draft state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. +PHEPs are not substantially modified after they have left the Draft state. Once resolution is reached, a PHEP is considered a historical document rather than a living specification and the PHEP number is a permanent identifier for the document. Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. -Final PHEPs are immutable and must be replaced by new PHEPs if necessary, rather than updated. The scope of a PHEP should be carefully considered in this light. A PHEP should also be written to be appropriately flexible to changes in technical details that do not affect the core purpose of the PHEP, e.g. specific URI's. The division of details between the PHEP and the reference implementation should be chosen carefully. +Final PHEPs are largely immutable and must be replaced by new PHEPs if substantive changes are needed, rather than updated. The scope of a PHEP should be carefully considered in this light. A PHEP should also be written to be appropriately flexible to changes in technical details that do not affect the core purpose of the PHEP, e.g. specific URI's. The division of details between the PHEP and the reference implementation should be chosen carefully. A Final PHEP can be revised to accommodate changes that do not change its substance. The permissible scope can be described as changes that would reflect a "patch" or "subminor" version change in semantic versioning schemes; examples include: From 9351f28718c05a00147c54ab5dedf511f240b78b Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 7 Feb 2024 12:45:07 -0500 Subject: [PATCH 77/84] phep-0001: new post history date; update copyright --- pheps/phep-0001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index c89c126..0c6c025 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -8,7 +8,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023, 9-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023 +Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024 ``` # What is a PHEP? @@ -399,7 +399,7 @@ This document is placed in the public domain or under the CC0-1.0-Universal lice @techreport(phep1, author = {Jonathan T. Niehof}, title = {PHEP Purpose and Guidelines}, - year = {2023}, + year = {2023--2024}, type = {PHEP}, number = {1}, doi = {10.5281/zenodo.xxxxxxx} From aa043b58d9d8497accf50b98ffeb1fd341f772fa Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Thu, 8 Feb 2024 14:41:10 -0500 Subject: [PATCH 78/84] phep-0001: fix quick typo, 'data' of accepance --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 0c6c025..f2a2ed2 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -139,7 +139,7 @@ If no progress is being made on the PHEP, the editor should consult the author. If a PHEP fails to find consensus, the author may choose to modify it for reconsideration. The PHEP may be "Withdrawn" if the PHEP author themself decides that the PHEP is actually a bad idea, or has accepted that a competing proposal is a better alternative. A PHEP can also "Rejected" if it fails to find consensus and the author is not willing or able to modify it. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. -When a PHEP changes state, the PHEP preamble must be updated accordingly. In addition to updating the Status field, the Resolution header must be added with a direct link to the minutes of the telecons and meetings where a decision on the PHEP was made. The Revision section must be updated with the data of acceptance, as appropriate. The editors must post announcements of PHEP resolution to the PyHC mailing list. +When a PHEP changes state, the PHEP preamble must be updated accordingly. In addition to updating the Status field, the Resolution header must be added with a direct link to the minutes of the telecons and meetings where a decision on the PHEP was made. The Revision section must be updated with the date of acceptance, as appropriate. The editors must post announcements of PHEP resolution to the PyHC mailing list. Final PHEPs can also be replaced by a different PHEP, rendering the original obsolete. From 4d6343648dc7b52f76b98daa323cc432517080cb Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 28 Feb 2024 09:37:34 -0500 Subject: [PATCH 79/84] phep-0001: clarify citation must include "version" DOI --- pheps/phep-0001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index f2a2ed2..8e10173 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -153,7 +153,7 @@ Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors or author 2. Puts the current date in the Post-History header. 3. Updates the Revisions section with the date accepted or rejected, as appropriate. 4. Updates the copyright date as necessary. -6. Updates the DOI in the citation with a new DOI that the editors have reserved +6. Updates the DOI in the citation with a new DOI that the editors have reserved. The editors merge the PR into `main` (maintaining the commit history). They tag the resulting commit and mint the reserved DOI. If the new PHEP replaces an existing one, the new DOI should be marked as a new version of the previous, and the Replaced PHEP must have the `Replaced-By` field in its header updated (see [PHEP Maintenance](#phep-maintenance)). @@ -224,7 +224,7 @@ Each PHEP should have the following elements, where they are applicable. It is s 13. **Revisions** - Brief summary of changes by revision number, including the date of approval. -14. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) and include citation information (see this PHEP for an example). +14. **Copyright/license** - Each new PHEP must be placed under a dual license of public domain and [CC0-1.0-Universal](https://creativecommons.org/publicdomain/zero/1.0/) and include citation information (see this PHEP for an example). The citation must include the DOI for the specific revision of the PHEP, although a DOI for all revisions of the PHEP may also be minted. # PHEP Formats and Templates From 7a47c0e7020dc3930e2d681d1ed4ead533fcf5a1 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 28 Feb 2024 09:44:50 -0500 Subject: [PATCH 80/84] phep-0001: mark mutability resolved again, clarify language --- pheps/phep-0001.md | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 8e10173..945a86f 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -342,6 +342,24 @@ Effort may go into a reference implementation for a standard that then gets vote As originally proposed PHEPs were limited to ASCII where practicable. This was deemed overly restrictive; authors should have some freedom of format and style, and it's up to the authors and editors to ensure this is both reasonable and consistent within a PHEP. CommonMark specifies Unicode without an encoding. +## Immutability of PHEPs + +As currently written, PHEPs are laregly [immutable](#phep-maintenance) once Final. Substantive changes require replacement rather than modification. This maintains clarity of reference, "PHEP-x" rather than "PHEP-x version y", and avoids confusion arising from rolling updates. It encourages getting the PHEP correct before first acceptance. Finally, it removes the need to define and document an update process. + +A PHEP can be updated by introducing a new PHEP that starts with and builds on the original text. Everything is then open for discussion. This encourages complete re-evaluation if the community reaches the point where something is important enough to revisit. + +On the downside, immutability discourages substantive but still small and potentially useful changes. It could make more work by requiring submission of a new PHEP. + +From the immutability discussion, a streamlined [process](#phep-maintenance) was introduced for making very small changes, such as fixing typos. This process also accommodates previously implicit changes such as marking a PHEP as replaced or withdrawn after final. + +The possible approaches that emerged from discussion roughly span the range: + +1. Pure immutability, a PHEP cannot be changed after it is Final. This has conceptually the simplest process (fewest possible steps, headers etc.) but is inflexible. +2. Allowing non-substantive changes to be undertaken without community review; PHEP-1 is written to this standard. +3. Allowing some level of substantive change with potentially more streamlined review, without drafting a new PHEP. This is perhaps the most flexible approach. + +One of the reasons for minimizing streamlined changes is the lack of a central decision-making authority; there is, at this writing, no PyHC steering committee or similar, that can assume responsibility for approvals in the absence of community consensus. A future PHEP can be introduced replacing PHEP-1 to provide for a broader revision process. + ## Quorum requirement The [resolution process](#phep-review-resolution) does not require a quorum for a vote. Suggested quorum requirements included: @@ -369,24 +387,7 @@ Certain ideas regarding the format of the Markdown source were removed as more c # Open Issues - -## Mutability of PHEPs - -As currently written, PHEPs are [immutable](#phep-maintenance) once Final, requiring replacement rather than modification. This maintains clarity of reference, "PHEP-x" rather than "PHEP-x version y", and avoids confusion arising from rolling updates. It encourages getting the PHEP correct before first acceptance. Finally, it removes the need to define and document an update process. - -A PHEP can be updated by introducing a new PHEP that starts with and builds on the original text. Everything is then open for discussion. This encourages complete re-evaluation if the community reaches the point where something is important enough to revisit. - -On the downside, immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP. - -From the immutability discussion, a process was introduced for making very small changes, such as fixing typos. - -The possible approaches that emerged from discussion roughly span the range: - -1. Pure immutability, a PHEP cannot be changed after it is Final. This has conceptually the simplest process (fewest possible steps, headers etc.) but is inflexible. -2. Allowing non-substantive changes to be undertaken without community review; PHEP-1 is currently written to this standard. -3. Further allowing some level of substantive change with potentially more streamlined review, without drafting a new PHEP. This is perhaps the most flexible approach. - -One of the reasons for minimizing streamlined changes is the lack of a central decision-making authority; there is, at this writing, no PyHC steering committee or similar, that can assume responsibility for approvals in the absence of community consensus. A future PHEP can be introduced replacing PHEP-1 to provide for a broader revision process. +There are no remaining open issues. # Revisions From a4b3f558b9ffa712324e63ff6a83325cc69e367f Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 28 Feb 2024 09:45:09 -0500 Subject: [PATCH 81/84] phep-0001: new post history for new push --- pheps/phep-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 945a86f..0f49b25 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -8,7 +8,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024 +Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024, 28-Feb-2024 ``` # What is a PHEP? From 1f4a13950601aa6531efd05973e7d7796de0c77d Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 13 Mar 2024 11:46:42 -0400 Subject: [PATCH 82/84] phep-0001: per discussion at meeting, require review at future pyhc meetings --- pheps/phep-0001.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 0f49b25..1329121 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -8,7 +8,7 @@ Status: Draft Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024, 28-Feb-2024 +Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024, 28-Feb-2024, 13-Mar-2024 ``` # What is a PHEP? @@ -325,6 +325,8 @@ Disagreements with editors must be mediated by PyHC leadership (as documented in This PHEP is subject to the same review and acceptance process that it proposes. +PyHC leadership must ensure that discussion of the PHEP process is on the agenda of at least one regular PyHC meeting annually. + # Rationale PHEP 1 is based on [PEP 1](https://peps.python.org/pep-0001/), which is a process that has credibility in the Python community and has proven appropriate for a fairly large group, the PyHC community being (by definition) larger than the community for any one PyHC package. From this basis, changes were made to make the process relevant to PyHC and to streamline where practicable. From 6d87152bb44ceb4ae80a407f6f7777bb878ac173 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 13 Mar 2024 12:07:17 -0400 Subject: [PATCH 83/84] phep-0001: add resolution header with first vote --- pheps/phep-0001.md | 1 + 1 file changed, 1 insertion(+) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 1329121..80e70ed 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -9,6 +9,7 @@ Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024, 28-Feb-2024, 13-Mar-2024 +Resolution: https://docs.google.com/document/d/1htbibknl1Npv1hQ1O4L22RKO_s8uc9dZT1iTJ49nMJg/edit#heading=h.a0b498f5euue ``` # What is a PHEP? From a45f178e491e98dcd2209de6621591c6cb2e1b19 Mon Sep 17 00:00:00 2001 From: Jon Niehof Date: Wed, 17 Apr 2024 12:28:02 -0400 Subject: [PATCH 84/84] phep-0001: mark as final, add DOI and related approval information * Some folding of headers as well --- pheps/phep-0001.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/pheps/phep-0001.md b/pheps/phep-0001.md index 80e70ed..f242e4c 100644 --- a/pheps/phep-0001.md +++ b/pheps/phep-0001.md @@ -4,12 +4,14 @@ Title: PHEP Purpose and Guidelines Author: Jonathan T. Niehof Discussions-To: https://github.com/heliophysicsPy/standards/pull/22 Revision: 1 -Status: Draft +Status: Final Type: Process Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 20-Oct-2023 -Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024, 28-Feb-2024, 13-Mar-2024 -Resolution: https://docs.google.com/document/d/1htbibknl1Npv1hQ1O4L22RKO_s8uc9dZT1iTJ49nMJg/edit#heading=h.a0b498f5euue +Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, + 07-Feb-2024, 28-Feb-2024, 13-Mar-2024, 20-May-2024 +Resolution: https://docs.google.com/document/d/1htbibknl1Npv1hQ1O4L22RKO_s8uc9dZT1iTJ49nMJg/edit#heading=h.a0b498f5euue, + https://docs.google.com/document/d/1RNGKHSf1S562WmDhCdYAAy3wG2tl6LT3-KBFYmRXTnA/edit ``` # What is a PHEP? @@ -394,7 +396,7 @@ There are no remaining open issues. # Revisions -Revision 1 (pending): Initial approval. +Revision 1 (15-Apr-2024): Initial approval. # Copyright @@ -406,7 +408,7 @@ This document is placed in the public domain or under the CC0-1.0-Universal lice year = {2023--2024}, type = {PHEP}, number = {1}, - doi = {10.5281/zenodo.xxxxxxx} + doi = {10.5281/zenodo.10988007} ) ```