Last active
February 28, 2024 14:48
-
-
Save jtniehof/63e9ce37f6749fbadb0d4f662ffa599a to your computer and use it in GitHub Desktop.
PHEP-0001 diffs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <meta charset="UTF-8"> | |
| <title>diff</title> | |
| <meta name="Generator" content="Vim/8.2"> | |
| <meta name="plugin-version" content="vim8.1_v2"> | |
| <meta name="settings" content="whole_filler,use_css,pre_wrap,no_foldcolumn,prevent_copy=,use_input_for_pc=fallback"> | |
| <meta name="colorscheme" content="none"> | |
| <style> | |
| <!-- | |
| pre { white-space: pre-wrap; font-family: monospace; color: #000000; background-color: #ffffff; } | |
| body { font-family: monospace; color: #000000; background-color: #ffffff; } | |
| * { font-size: 1em; } | |
| .Identifier { color: #008080; } | |
| .Statement { color: #af5f00; } | |
| .Constant { color: #c00000; } | |
| .htmlItalic { font-style: italic; } | |
| .Title { color: #c000c0; } | |
| .Underlined { color: #c000c0; text-decoration: underline; } | |
| .htmlBold { font-weight: bold; } | |
| .Type { color: #008000; } | |
| .Special { color: #c000c0; } | |
| .DiffAdd { background-color: #5fd7ff; padding-bottom: 1px; } | |
| .DiffChange { background-color: #ffd7ff; padding-bottom: 1px; } | |
| .DiffDelete { color: #8080ff; background-color: #afffff; padding-bottom: 1px; } | |
| .DiffText { background-color: #ff6060; padding-bottom: 1px; font-weight: bold; } | |
| --> | |
| <!-- | |
| table { table-layout: fixed; } | |
| html, body, table, tbody { width: 100%; margin: 0; padding: 0; } | |
| table, td, th { border: 1px solid; } | |
| td { vertical-align: top; } | |
| th, td { width: 50.0%; } | |
| td div { overflow: auto; } | |
| --> | |
| </style> | |
| </head> | |
| <body> | |
| <table id='vimCodeElement'> | |
| <tr> | |
| <th>./sixth_pr.md</th> | |
| <th>phep-0001.md</th> | |
| </tr><tr> | |
| <td><div> | |
| <pre> | |
| <span class="Special">```</span> | |
| PHEP: 1 | |
| Title: PHEP Purpose and Guidelines | |
| Author: Jonathan T. Niehof <jtniehof@gmail.com> <<a href="https://orcid.org/0000-0001-6286-5809">https://orcid.org/0000-0001-6286-5809</a>> | |
| Discussions-To: <a href="https://github.com/heliophysicsPy/standards/pull/22">https://github.com/heliophysicsPy/standards/pull/22</a> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| Status: Draft | |
| Type: Process | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| Created: 20-Oct-2023 | |
| <span class="DiffChange">Post-History: 24-Oct-2023, 31-Oct-2023, </span><span class="DiffText">9-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023</span> | |
| <span class="Special">```</span> | |
| <span class="Special">#</span><span class="Title"> What is a PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-is-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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, 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. | |
| <span class="DiffChange">Because PHEPs are maintained as text files in a versioned repository, their </span><span class="DiffText">revision history is the historical record of the feature proposal. This record is available by the normal git commands for retrieving older revision</span><span class="DiffChange">s and can be browsed </span><span class="DiffChange">[</span><span class="Underlined DiffChange">on GitHub</span><span class="DiffChange">]</span><span class="DiffChange">(</span><span class="Constant DiffChange"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span><span class="DiffChange">)</span><span class="DiffChange">.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Motivation</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-motivation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>) 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Audience</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-audience"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Types</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-type"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| There are three types of PHEP: | |
| <span class="Statement">1.</span> A <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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 [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>). Examples include testing requirements, OS support, and dependency handling. | |
| <span class="Statement">2.</span> An <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> 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. | |
| <span class="Statement">3.</span> A <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Applicability</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-applicability"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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. | |
| <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. | |
| <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> PHEPs determine the process by which the PyHC community makes formal decisions and as such bind all participants in PyHC. | |
| <span class="DiffChange">A PHEP may provide further guidance on its applicability and implementation (e.g. timelines for compliance). PHEPs </span><span class="DiffText">that define the applicability of other PHEPs</span><span class="DiffChange"> are usually Process PHEPs.</span> | |
| For all three types, key words in PHEPs must be interpreted according to [<span class="Underlined">RFC2119</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a></span>); the use of <span class="Special">`</span>must<span class="Special">`</span>, <span class="Special">`</span>must not<span class="Special">`</span>, <span class="Special">`</span>should<span class="Special">`</span>, and <span class="Special">`</span>should not<span class="Special">`</span> are preferred. | |
| <span class="Special">#</span><span class="Title"> PHEP Workflow</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-workflow"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| All PHEP workflow is conducted via the [<span class="Underlined">GitHub PyHC standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Editors</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-editors"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">PHEP Editor Responsibilities & Workflow</span>](<span class="Constant">#phep-editor-responsibilities-workflow</span>) 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 <span class="Special">`</span>@heliophysicsPy/phep-editors<span class="Special">`</span> on GitHub. | |
| <span class="Special">##</span><span class="Title"> Start with an idea</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"start-with-an-idea"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">telecon</span>](<span class="Constant"><a href="https://heliopython.org/meetings/">https://heliopython.org/meetings/</a></span>), other established PyHC [<span class="Underlined">discussion channels</span>](<span class="Constant"><a href="https://heliopython.org/contact/">https://heliopython.org/contact/</a></span>) including the email list or Matrix/Slack, and [<span class="Underlined">an issue in the standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/issues/new/choose">https://github.com/heliophysicsPy/standards/issues/new/choose</a></span>) (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. | |
| 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 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. | |
| <span class="Special">##</span><span class="Title"> Submitting a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"submitting-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The proposal must be submitted as a draft PHEP via a [<span class="Underlined">GitHub pull request</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/pulls">https://github.com/heliophysicsPy/standards/pulls</a></span>). The draft must be written in PHEP style as described below. The editors may correct minor errors. | |
| The standard PHEP workflow is: | |
| <span class="Statement">*</span> You, the PHEP author, fork the PyHC [<span class="Underlined">standards</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>) repository, and create a file named <span class="Special">`</span>phep-9999.md<span class="Special">`</span> that contains your new PHEP. Use "9999" as your draft PHEP number. | |
| <span class="Statement">*</span> In the "Type:" header field, enter "Standards Track", "Informational", or "Process" as appropriate, and for the "Status:" field enter "Draft". For full details, see [<span class="Underlined">PHEP Header Preamble</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">*</span> Push this to a branch (not <span class="Special">`</span>main<span class="Special">`</span>) 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. | |
| <span class="Statement">*</span> The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: | |
| <span class="Statement"> *</span> It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. | |
| <span class="Statement"> *</span> It is of reasonable scope, not too broad or unfocused. | |
| <span class="Statement"> *</span> The title accurately describes the content. | |
| <span class="Statement"> *</span> 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. | |
| If the PHEP isn't ready for approval, an editor will send it back to the author with specific instructions. | |
| <span class="Statement">*</span> 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 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. | |
| <span class="Special">##</span><span class="Title"> Discussing a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"discussing-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 <span class="Special">`</span>Discussions-To<span class="Special">`</span> 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 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 <span class="Special">`</span>Post-History<span class="Special">`</span> 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. | |
| 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. | |
| <span class="DiffChange">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 </span><span class="Special DiffChange">`</span><span class="DiffChange">Discussions-To</span><span class="Special DiffChange">`</span><span class="DiffChange"> link must be updated.</span> | |
| PHEP discussions are subject to the [<span class="Underlined">PyHC Code of Conduct</span>](<span class="Constant"><a href="https://heliopython.org/docs/code_of_conduct/">https://heliopython.org/docs/code_of_conduct/</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Review & Resolution</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-review-resolution"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">discussion</span>](<span class="Constant">#discussing-a-phep</span>) 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. | |
| <span class="DiffChange">A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, </span><span class="DiffText">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</span><span class="DiffChange">. 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.</span> | |
| 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. | |
| <span class="DiffChange">"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.</span> | |
| 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, 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, [<span class="Underlined">transfer it to another author</span>](<span class="Constant">transferring-phep-ownership</span>), 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. 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. | |
| <span class="DiffChange">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.</span> | |
| 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: | |
| ![<span class="Underlined">PHEP status flow diagram</span>](<span class="Constant">phep-0001/process_flow.svg</span>) | |
| <span class="DiffChange">Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors </span><span class="DiffText">update the preamble and merge the PR into </span><span class="Special DiffText">`</span><span class="DiffText">main</span><span class="Special DiffText">`</span><span class="DiffText"> (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 </span><span class="Special DiffText">`</span><span class="DiffText">Replaced-By</span><span class="Special DiffText">`</span><span class="DiffText"> field in its header updated.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| The complete PHEP approval process is: | |
| ![<span class="Underlined">PHEP workflow diagram</span>](<span class="Constant">phep-0001/workflow.svg</span>) | |
| 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. | |
| <span class="Special">##</span><span class="Title"> PHEP Maintenance</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-maintenance"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="DiffChange">PHEPs are no</span><span class="DiffText"> longer</span><span class="DiffChange"> 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.</span> | |
| Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. | |
| <span class="DiffText">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 </span><span class="Special DiffText">`</span><span class="DiffText">standards</span><span class="Special DiffText">`</span><span class="DiffText"> repository, merged by PHEP editors</span><span class="DiffChange">.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Special">#</span><span class="Title"> What belongs in a successful PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-belongs-in-a-successful-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Statement">1.</span> <span class="htmlBold">**</span><span class="htmlBold">Preamble</span><span class="htmlBold">**</span> - [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style headers containing metadata about the PHEP, described [<span class="Underlined">below</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">2.</span> <span class="htmlBold">**</span><span class="htmlBold">Abstract</span><span class="htmlBold">**</span> - a short (~200 word) description of the issue being addressed. | |
| <span class="Statement">3.</span> <span class="htmlBold">**</span><span class="htmlBold">Motivation</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">4.</span> <span class="htmlBold">**</span><span class="htmlBold">Rationale</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">5.</span> <span class="htmlBold">**</span><span class="htmlBold">Specification</span><span class="htmlBold">**</span> - The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. | |
| <span class="Statement">6.</span> <span class="htmlBold">**</span><span class="htmlBold">Backwards Compatibility</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">7.</span> <span class="htmlBold">**</span><span class="htmlBold">Security Implications</span><span class="htmlBold">**</span> - Any security concerns should be explicitly written out. | |
| <span class="Statement DiffChange">8.</span><span class="DiffChange"> </span><span class="htmlBold DiffChange">**</span><span class="htmlBold DiffChange">How to Teach This</span><span class="htmlBold DiffChange">**</span><span class="DiffChange"> - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work.</span> | |
| <span class="Statement">9.</span> <span class="htmlBold">**</span><span class="htmlBold">Reference Implementation</span><span class="htmlBold">**</span> - 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). | |
| <span class="Statement">10.</span> <span class="htmlBold">**</span><span class="htmlBold">Rejected Ideas</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">11.</span> <span class="htmlBold">**</span><span class="htmlBold">Open Issues</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">12.</span> <span class="htmlBold">**</span><span class="htmlBold">Footnotes</span><span class="htmlBold">**</span> - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. | |
| <span class="Statement DiffChange">13.</span><span class="DiffChange"> </span><span class="htmlBold DiffChange">**</span><span class="htmlBold DiffText">Copyright/license</span><span class="htmlBold DiffText">**</span><span class="DiffText"> - Each new PHEP must be placed under a dual license of public domain and </span><span class="DiffText">[</span><span class="Underlined DiffText">CC0-1.0-Universal</span><span class="DiffText">]</span><span class="DiffText">(</span><span class="Constant DiffText"><a href="https://creativecommons.org/publicdomain/zero/1.0/">https://creativecommons.org/publicdomain/zero/1.0/</a></span><span class="DiffText">)</span><span class="DiffText"> and include citation information (see this PHEP for an example)</span><span class="DiffChange">.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Formats and Templates</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-formats-and-templates"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">CommonMark specification</span>](<span class="Constant"><a href="https://spec.commonmark.org/">https://spec.commonmark.org/</a></span>) at the time the PHEP is approved. PHEPs must not use [<span class="Underlined">GitHub extensions</span>](<span class="Constant"><a href="https://github.github.com/gfm/">https://github.github.com/gfm/</a></span>). | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Header Preamble</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-header-preamble"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Each PHEP must begin with an [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style header preamble, marked off with a [<span class="Underlined">code fence</span>](<span class="Constant"><a href="https://spec.commonmark.org/current/#fenced-code-blocks">https://spec.commonmark.org/current/#fenced-code-blocks</a></span>). The headers must appear in the following order. Headers marked with "<span class="htmlItalic">*</span><span class="htmlItalic">" are optional. All other headers are required.</span> | |
| ``` | |
| PHEP: <phep number> | |
| Title: <phep title> | |
| Author: <list of authors' real names; optionally, email addrs and/or ORCIDs> | |
| Discussions-To: <URL of current PR> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| Status: <Draft | Rejected | Withdrawn | Final | Replaced> | |
| Type: <Standards Track | Informational | Process> | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| <span class="Statement"> *</span><span class="htmlItalic"> Requires: <phep numbers></span> | |
| Created: <date created on, in dd-mmm-yyyy format> | |
| <span class="DiffChange"> Post-History: <dates, in dd-mmm-yyyy format</span><span class="DiffText">,</span><span class="DiffChange"> </span> | |
| <span class="DiffAdd"> inline-linked to PHEP discussion threads></span><span class="DiffAdd"> </span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaces: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaced-By: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Resolution: <url></span> | |
| ``` | |
| <span class="htmlItalic">The Author header lists the names and optionally the email addresses and/or [ORCIDs](<a href="https://orcid.org)">https://orcid.org)</a> of all the authors of the PHEP. The format of the Author header values must be:</span> | |
| <span class="htmlItalic">`Random J. User <random@example.com> <<a href="https://orcid.org/0000-0000-0000-0000">https://orcid.org/0000-0000-0000-0000</a>>`</span> | |
| <span class="htmlItalic">if the email address and ORCID are included, and just:</span> | |
| <span class="htmlItalic">`Random J. User`</span> | |
| <span class="htmlItalic">for just the name (similarly for ORCID without email address and vice versa).</span> | |
| <span class="htmlItalic">If there are multiple authors, each should be on a separate line following [RFC 2822](<a href="https://datatracker.ietf.org/doc/html/rfc2822.html)">https://datatracker.ietf.org/doc/html/rfc2822.html)</a> continuation line conventions.</span> | |
| <span class="htmlItalic">The Discussions-To header provides the URL to the current PR discussion thread for the PHEP.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="htmlItalic">The Type header specifies the [type](#phep-type) of PHEP: Standards Track, Informational, or Process.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP depends on.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Auxiliary Files</span> | |
| <span class="htmlItalic"><a name="auxiliary-files"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Transferring PHEP Ownership</span> | |
| <span class="htmlItalic"><a name="transferring-phep-ownership"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Editor Responsibilities & Workflow</span> | |
| <span class="htmlItalic"><a name="phep-editor-responsibilities-workflow"></a></span> | |
| <span class="htmlItalic">A PHEP editor must be added to the `@heliophysicsPy/phep-editors` group on GitHub and must watch the `standards` repository.</span> | |
| <span class="htmlItalic">For each new PHEP that comes in, an editor does the following:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The title should accurately describe the content.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The PHEP's type is correctly labeled ("Standards Track", "Informational", or "Process"), and its status is "Draft".</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The file name extension is correct (i.e. `.md`).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic DiffChange">If the PHEP isn't ready, an editor will send it back to the author for </span><span class="htmlItalic DiffText">revision</span><span class="htmlItalic DiffChange">, with specific instructions.</span> | |
| <span class="htmlItalic">Once the PHEP is ready for discussion, a PHEP editor will:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Assign a PHEP number (almost always the next available number).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Ask the author to update the PHEP with the PR link, mark the PR ready for review, and post an announcement.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP 1 Acceptance</span> | |
| <span class="htmlItalic"><a name="phep-1-acceptance"></a></span> | |
| <span class="htmlItalic">This PHEP is subject to the same review and acceptance process that it proposes.</span> | |
| <span class="Special">#</span><span class="Title"> Rationale</span> | |
| <span class="htmlItalic"><a name="rationale"></a></span> | |
| <span class="htmlItalic">PHEP 1 is based on [PEP 1](<a href="https://peps.python.org/pep-0001/)">https://peps.python.org/pep-0001/)</a>, 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.</span> | |
| <span class="Special">#</span><span class="Title"> Rejected Ideas</span> | |
| <span class="htmlItalic"><a name="rejected-ideas"></a></span> | |
| <span class="Special">##</span><span class="Title"> Acceptance without reference implementation</span> | |
| <span class="htmlItalic"><a name="acceptance-without-reference-implementation"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> ASCII encoding</span> | |
| <span class="htmlItalic"><a name="ascii-encoding"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special DiffChange">##</span><span class="Title DiffChange"> </span><span class="Title DiffText">M</span><span class="Title DiffChange">utability of PHEPs</span><span class="DiffChange"> </span> | |
| <span class="htmlItalic"><a name="immutability-of-pheps"></a></span> | |
| <span class="htmlItalic DiffText">PHEPs are [immutable](#phep-maintenance) once Final, requiring</span><span class="htmlItalic DiffChange"> 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.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="htmlItalic DiffText">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</span><span class="htmlItalic DiffChange">.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="htmlItalic DiffChange">On</span><span class="htmlItalic DiffText"> the downside, immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP</span><span class="htmlItalic DiffChange">.</span> | |
| <span class="Special">##</span><span class="Title"> Quorum requirement</span> | |
| <span class="htmlItalic"><a name="quorum-requirement"></a></span> | |
| <span class="htmlItalic">The [resolution process](#phep-review-resolution) does not require a quorum for a vote. Suggested quorum requirements included:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring "substantial community representation" at a vote.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring representation from at least one core package at a vote.</span> | |
| <span class="Statement DiffAdd">*</span><span class="htmlItalic DiffAdd"> Requiring the author of the PHEP to at least be present for the vote.</span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Objections may be raised in the PR, so nobody need be present to break consensus for acceptance.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The minimum one-month notice before the meeting allows objections to be raised.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic">As consensus is required, any of these "nays" carry the vote.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Special">##</span><span class="Title"> Recording names at acceptance</span> | |
| <span class="htmlItalic"><a name="recording-names-at-acceptance"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> Source formatting</span> | |
| <span class="htmlItalic"><a name="source-formatting"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Open Issues</span> | |
| <span class="htmlItalic"><a name="open-issues"></a></span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic">There are no remaining open issues.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Special">#</span><span class="Title"> Copyright</span> | |
| <span class="htmlItalic"><a name="copyright"></a></span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">@techreport(phep1,</span> | |
| <span class="htmlItalic"> author = {Jonathan T. Niehof},</span> | |
| <span class="htmlItalic"> title = {PHEP Purpose and Guidelines},</span> | |
| <span class="DiffChange"> year = {2023},</span><span class="DiffChange"> </span> | |
| type = {PHEP}, | |
| <span class="htmlItalic"> number = {1},</span> | |
| doi = {10.5281/zenodo.xxxxxxx} | |
| <span class="htmlItalic">)</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">This document draws from:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://peps.python.org/pep-0001/">https://peps.python.org/pep-0001/</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://numpy.org/neps/nep-0000.html">https://numpy.org/neps/nep-0000.html</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md">https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md</a>></span> | |
| </pre> | |
| </div></td> | |
| <td><div> | |
| <pre> | |
| <span class="Special">```</span> | |
| PHEP: 1 | |
| Title: PHEP Purpose and Guidelines | |
| Author: Jonathan T. Niehof <jtniehof@gmail.com> <<a href="https://orcid.org/0000-0001-6286-5809">https://orcid.org/0000-0001-6286-5809</a>> | |
| Discussions-To: <a href="https://github.com/heliophysicsPy/standards/pull/22">https://github.com/heliophysicsPy/standards/pull/22</a> | |
| <span class="DiffAdd">Revision: 1</span><span class="DiffAdd"> </span> | |
| Status: Draft | |
| Type: Process | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| Created: 20-Oct-2023 | |
| <span class="DiffChange">Post-History: 24-Oct-2023, 31-Oct-2023, </span><span class="DiffText">09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024, 28-Feb-2024</span> | |
| <span class="Special">```</span> | |
| <span class="Special">#</span><span class="Title"> What is a PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-is-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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, 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. | |
| <span class="DiffChange">Because PHEPs are maintained as text files in a versioned repository, their </span><span class="DiffText">commit history is the historical record of the feature proposal. This record is available by the normal git commands for retrieving older commit</span><span class="DiffChange">s and can be browsed </span><span class="DiffChange">[</span><span class="Underlined DiffChange">on GitHub</span><span class="DiffChange">]</span><span class="DiffChange">(</span><span class="Constant DiffChange"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span><span class="DiffChange">)</span><span class="DiffChange">.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Motivation</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-motivation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>) 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Audience</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-audience"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Types</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-type"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| There are three types of PHEP: | |
| <span class="Statement">1.</span> A <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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 [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>). Examples include testing requirements, OS support, and dependency handling. | |
| <span class="Statement">2.</span> An <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> 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. | |
| <span class="Statement">3.</span> A <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Applicability</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-applicability"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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. | |
| <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. | |
| <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> PHEPs determine the process by which the PyHC community makes formal decisions and as such bind all participants in PyHC. | |
| <span class="DiffChange">A PHEP may provide further guidance on its applicability and implementation (e.g. timelines for compliance). PHEPs </span><span class="DiffText">may define the applicability of other PHEPs; these</span><span class="DiffChange"> are usually Process PHEPs.</span> | |
| For all three types, key words in PHEPs must be interpreted according to [<span class="Underlined">RFC2119</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a></span>); the use of <span class="Special">`</span>must<span class="Special">`</span>, <span class="Special">`</span>must not<span class="Special">`</span>, <span class="Special">`</span>should<span class="Special">`</span>, and <span class="Special">`</span>should not<span class="Special">`</span> are preferred. | |
| <span class="Special">#</span><span class="Title"> PHEP Workflow</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-workflow"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| All PHEP workflow is conducted via the [<span class="Underlined">GitHub PyHC standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Editors</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-editors"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">PHEP Editor Responsibilities & Workflow</span>](<span class="Constant">#phep-editor-responsibilities-workflow</span>) 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 <span class="Special">`</span>@heliophysicsPy/phep-editors<span class="Special">`</span> on GitHub. | |
| <span class="Special">##</span><span class="Title"> Start with an idea</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"start-with-an-idea"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">telecon</span>](<span class="Constant"><a href="https://heliopython.org/meetings/">https://heliopython.org/meetings/</a></span>), other established PyHC [<span class="Underlined">discussion channels</span>](<span class="Constant"><a href="https://heliopython.org/contact/">https://heliopython.org/contact/</a></span>) including the email list or Matrix/Slack, and [<span class="Underlined">an issue in the standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/issues/new/choose">https://github.com/heliophysicsPy/standards/issues/new/choose</a></span>) (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. | |
| 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 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. | |
| <span class="Special">##</span><span class="Title"> Submitting a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"submitting-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The proposal must be submitted as a draft PHEP via a [<span class="Underlined">GitHub pull request</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/pulls">https://github.com/heliophysicsPy/standards/pulls</a></span>). The draft must be written in PHEP style as described below. The editors may correct minor errors. | |
| The standard PHEP workflow is: | |
| <span class="Statement">*</span> You, the PHEP author, fork the PyHC [<span class="Underlined">standards</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>) repository, and create a file named <span class="Special">`</span>phep-9999.md<span class="Special">`</span> that contains your new PHEP. Use "9999" as your draft PHEP number. | |
| <span class="Statement">*</span> In the "Type:" header field, enter "Standards Track", "Informational", or "Process" as appropriate, and for the "Status:" field enter "Draft". For full details, see [<span class="Underlined">PHEP Header Preamble</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">*</span> Push this to a branch (not <span class="Special">`</span>main<span class="Special">`</span>) 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. | |
| <span class="Statement">*</span> The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: | |
| <span class="Statement"> *</span> It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. | |
| <span class="Statement"> *</span> It is of reasonable scope, not too broad or unfocused. | |
| <span class="Statement"> *</span> The title accurately describes the content. | |
| <span class="Statement"> *</span> 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. | |
| If the PHEP isn't ready for approval, an editor will send it back to the author with specific instructions. | |
| <span class="Statement">*</span> 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 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. | |
| <span class="Special">##</span><span class="Title"> Discussing a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"discussing-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 <span class="Special">`</span>Discussions-To<span class="Special">`</span> 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 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 <span class="Special">`</span>Post-History<span class="Special">`</span> 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. | |
| 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. | |
| <span class="DiffChange">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 </span><span class="Special DiffChange">`</span><span class="DiffChange">Discussions-To</span><span class="Special DiffChange">`</span><span class="DiffChange"> link must be updated</span><span class="DiffText">, and the new PR discussion should link to the old for reference</span><span class="DiffChange">.</span> | |
| PHEP discussions are subject to the [<span class="Underlined">PyHC Code of Conduct</span>](<span class="Constant"><a href="https://heliopython.org/docs/code_of_conduct/">https://heliopython.org/docs/code_of_conduct/</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Review & Resolution</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-review-resolution"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">discussion</span>](<span class="Constant">#discussing-a-phep</span>) 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. | |
| <span class="DiffChange">A PHEP is accepted by consensus of attendees (virtual or in-person) at both a PyHC regular telecon and a regular PyHC meeting, </span><span class="DiffText">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 </span><span class="htmlItalic DiffText">*</span><span class="htmlItalic DiffText">after</span><span class="htmlItalic DiffText">*</span><span class="DiffText"> the previous vote, effectively requiring a month between votes</span><span class="DiffChange">. 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.</span> | |
| 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. | |
| <span class="DiffChange">"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.</span><span class="DiffText"> 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.</span> | |
| 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, 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, [<span class="Underlined">transfer it to another author</span>](<span class="Constant">transferring-phep-ownership</span>), 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. 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. | |
| <span class="DiffChange">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 </span><span class="DiffText">Revision section must be updated with the date of acceptance, as appropriate. The </span><span class="DiffChange">editors must post announcements of PHEP resolution to the PyHC mailing list.</span> | |
| 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: | |
| ![<span class="Underlined">PHEP status flow diagram</span>](<span class="Constant">phep-0001/process_flow.svg</span>) | |
| <span class="DiffChange">Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors </span><span class="DiffText">or author push a commit to the PR branch which:</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Statement DiffAdd">1.</span><span class="DiffAdd"> Updates the Status appropriately. </span> | |
| <span class="Statement DiffAdd">2.</span><span class="DiffAdd"> Puts the current date in the Post-History header. </span> | |
| <span class="Statement DiffAdd">3.</span><span class="DiffAdd"> Updates the Revisions section with the date accepted or rejected, as appropriate.</span> | |
| <span class="Statement DiffAdd">4.</span><span class="DiffAdd"> Updates the copyright date as necessary. </span> | |
| <span class="Statement DiffAdd">6.</span><span class="DiffAdd"> Updates the DOI in the citation with a new DOI that the editors have reserved.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd">The editors merge the PR into </span><span class="Special DiffAdd">`</span><span class="DiffAdd">main</span><span class="Special DiffAdd">`</span><span class="DiffAdd"> (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 </span><span class="Special DiffAdd">`</span><span class="DiffAdd">Replaced-By</span><span class="Special DiffAdd">`</span><span class="DiffAdd"> field in its header updated (see </span><span class="DiffAdd">[</span><span class="Underlined DiffAdd">PHEP Maintenance</span><span class="DiffAdd">]</span><span class="DiffAdd">(</span><span class="Constant DiffAdd">#phep-maintenance</span><span class="DiffAdd">)</span><span class="DiffAdd">).</span> | |
| The complete PHEP approval process is: | |
| ![<span class="Underlined">PHEP workflow diagram</span>](<span class="Constant">phep-0001/workflow.svg</span>) | |
| 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. | |
| <span class="Special">##</span><span class="Title"> PHEP Maintenance</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-maintenance"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="DiffChange">PHEPs are no</span><span class="DiffText">t</span><span class="DiffChange"> 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.</span> | |
| Rejected and Withdrawn PHEPs must not be resurrected but may be used as the basis for a new PHEP. | |
| <span class="DiffText">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</span><span class="DiffChange">.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd">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:</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Statement DiffAdd">1.</span><span class="DiffAdd"> A PHEP is Replaced due to acceptance of a new PHEP, requiring an update to the header.</span> | |
| <span class="Statement DiffAdd">2.</span><span class="DiffAdd"> A clear typo, misspelling, or other error not affecting the meaning of a PHEP is found.</span> | |
| <span class="Statement DiffAdd">3.</span><span class="DiffAdd"> A URI or similar external reference is moved / updated. </span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd">To revise a PHEP, a PR must be opened with the following changes to the PHEP:</span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Statement DiffAdd">1.</span><span class="DiffAdd"> The Revision header is incremented by one. </span> | |
| <span class="Statement DiffAdd">2.</span><span class="DiffAdd"> The Status is updated to Replaced and the Replaced-By header updated if a PHEP has been replaced.</span> | |
| <span class="Statement DiffAdd">3.</span><span class="DiffAdd"> The Post-History header is updated with the date of the new PR. </span> | |
| <span class="Statement DiffAdd">4.</span><span class="DiffAdd"> A new entry is added in the Revisions section, briefly explaining the changes and the need for them.</span> | |
| <span class="Statement DiffAdd">5.</span><span class="DiffAdd"> The copyright date is updated as necessary. </span> | |
| <span class="Statement DiffAdd">6.</span><span class="DiffAdd"> A new DOI is reserved and the DOI updated in the citation. </span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd">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.</span> | |
| <span class="Special">#</span><span class="Title"> What belongs in a successful PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-belongs-in-a-successful-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Statement">1.</span> <span class="htmlBold">**</span><span class="htmlBold">Preamble</span><span class="htmlBold">**</span> - [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style headers containing metadata about the PHEP, described [<span class="Underlined">below</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">2.</span> <span class="htmlBold">**</span><span class="htmlBold">Abstract</span><span class="htmlBold">**</span> - a short (~200 word) description of the issue being addressed. | |
| <span class="Statement">3.</span> <span class="htmlBold">**</span><span class="htmlBold">Motivation</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">4.</span> <span class="htmlBold">**</span><span class="htmlBold">Rationale</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">5.</span> <span class="htmlBold">**</span><span class="htmlBold">Specification</span><span class="htmlBold">**</span> - The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. | |
| <span class="Statement">6.</span> <span class="htmlBold">**</span><span class="htmlBold">Backwards Compatibility</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">7.</span> <span class="htmlBold">**</span><span class="htmlBold">Security Implications</span><span class="htmlBold">**</span> - Any security concerns should be explicitly written out. | |
| <span class="Statement DiffChange">8.</span><span class="DiffChange"> </span><span class="htmlBold DiffChange">**</span><span class="htmlBold DiffChange">How to Teach This</span><span class="htmlBold DiffChange">**</span><span class="DiffChange"> - This section may include key points and recommended documentation changes that would help users, new and experienced, apply the PHEP to their work.</span><span class="DiffText"> 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.</span> | |
| <span class="Statement">9.</span> <span class="htmlBold">**</span><span class="htmlBold">Reference Implementation</span><span class="htmlBold">**</span> - 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). | |
| <span class="Statement">10.</span> <span class="htmlBold">**</span><span class="htmlBold">Rejected Ideas</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">11.</span> <span class="htmlBold">**</span><span class="htmlBold">Open Issues</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">12.</span> <span class="htmlBold">**</span><span class="htmlBold">Footnotes</span><span class="htmlBold">**</span> - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. | |
| <span class="Statement DiffChange">13.</span><span class="DiffChange"> </span><span class="htmlBold DiffChange">**</span><span class="htmlBold DiffText">Revisions</span><span class="htmlBold DiffText">**</span><span class="DiffText"> - Brief summary of changes by revision number, including the date of approval</span><span class="DiffChange">.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Statement DiffAdd">14.</span><span class="DiffAdd"> </span><span class="htmlBold DiffAdd">**</span><span class="htmlBold DiffAdd">Copyright/license</span><span class="htmlBold DiffAdd">**</span><span class="DiffAdd"> - Each new PHEP must be placed under a dual license of public domain and </span><span class="DiffAdd">[</span><span class="Underlined DiffAdd">CC0-1.0-Universal</span><span class="DiffAdd">]</span><span class="DiffAdd">(</span><span class="Constant DiffAdd"><a href="https://creativecommons.org/publicdomain/zero/1.0/">https://creativecommons.org/publicdomain/zero/1.0/</a></span><span class="DiffAdd">)</span><span class="DiffAdd"> 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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Formats and Templates</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-formats-and-templates"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">CommonMark specification</span>](<span class="Constant"><a href="https://spec.commonmark.org/">https://spec.commonmark.org/</a></span>) at the time the PHEP is approved. PHEPs must not use [<span class="Underlined">GitHub extensions</span>](<span class="Constant"><a href="https://github.github.com/gfm/">https://github.github.com/gfm/</a></span>). | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Header Preamble</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-header-preamble"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Each PHEP must begin with an [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style header preamble, marked off with a [<span class="Underlined">code fence</span>](<span class="Constant"><a href="https://spec.commonmark.org/current/#fenced-code-blocks">https://spec.commonmark.org/current/#fenced-code-blocks</a></span>). The headers must appear in the following order. Headers marked with "<span class="htmlItalic">*</span><span class="htmlItalic">" are optional. All other headers are required.</span> | |
| ``` | |
| PHEP: <phep number> | |
| Title: <phep title> | |
| Author: <list of authors' real names; optionally, email addrs and/or ORCIDs> | |
| Discussions-To: <URL of current PR> | |
| <span class="DiffAdd"> Revision: <phep version number></span><span class="DiffAdd"> </span> | |
| Status: <Draft | Rejected | Withdrawn | Final | Replaced> | |
| Type: <Standards Track | Informational | Process> | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| <span class="Statement"> *</span><span class="htmlItalic"> Requires: <phep numbers></span> | |
| Created: <date created on, in dd-mmm-yyyy format> | |
| <span class="DiffChange"> Post-History: <dates, in dd-mmm-yyyy format</span><span class="DiffText">></span><span class="DiffChange"> </span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaces: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaced-By: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Resolution: <url></span> | |
| ``` | |
| <span class="htmlItalic">The Author header lists the names and optionally the email addresses and/or [ORCIDs](<a href="https://orcid.org)">https://orcid.org)</a> of all the authors of the PHEP. The format of the Author header values must be:</span> | |
| <span class="htmlItalic">`Random J. User <random@example.com> <<a href="https://orcid.org/0000-0000-0000-0000">https://orcid.org/0000-0000-0000-0000</a>>`</span> | |
| <span class="htmlItalic">if the email address and ORCID are included, and just:</span> | |
| <span class="htmlItalic">`Random J. User`</span> | |
| <span class="htmlItalic">for just the name (similarly for ORCID without email address and vice versa).</span> | |
| <span class="htmlItalic">If there are multiple authors, each should be on a separate line following [RFC 2822](<a href="https://datatracker.ietf.org/doc/html/rfc2822.html)">https://datatracker.ietf.org/doc/html/rfc2822.html)</a> continuation line conventions.</span> | |
| <span class="htmlItalic">The Discussions-To header provides the URL to the current PR discussion thread for the PHEP.</span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic">The Type header specifies the [type](#phep-type) of PHEP: Standards Track, Informational, or Process.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP depends on.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Auxiliary Files</span> | |
| <span class="htmlItalic"><a name="auxiliary-files"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Transferring PHEP Ownership</span> | |
| <span class="htmlItalic"><a name="transferring-phep-ownership"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Editor Responsibilities & Workflow</span> | |
| <span class="htmlItalic"><a name="phep-editor-responsibilities-workflow"></a></span> | |
| <span class="htmlItalic">A PHEP editor must be added to the `@heliophysicsPy/phep-editors` group on GitHub and must watch the `standards` repository.</span> | |
| <span class="htmlItalic">For each new PHEP that comes in, an editor does the following:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The title should accurately describe the content.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The PHEP's type is correctly labeled ("Standards Track", "Informational", or "Process"), and its status is "Draft".</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The file name extension is correct (i.e. `.md`).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic DiffChange">If the PHEP isn't ready, an editor will send it back to the author for </span><span class="htmlItalic DiffText">updates</span><span class="htmlItalic DiffChange">, with specific instructions.</span> | |
| <span class="htmlItalic">Once the PHEP is ready for discussion, a PHEP editor will:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Assign a PHEP number (almost always the next available number).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Ask the author to update the PHEP with the PR link, mark the PR ready for review, and post an announcement.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP 1 Acceptance</span> | |
| <span class="htmlItalic"><a name="phep-1-acceptance"></a></span> | |
| <span class="htmlItalic">This PHEP is subject to the same review and acceptance process that it proposes.</span> | |
| <span class="Special">#</span><span class="Title"> Rationale</span> | |
| <span class="htmlItalic"><a name="rationale"></a></span> | |
| <span class="htmlItalic">PHEP 1 is based on [PEP 1](<a href="https://peps.python.org/pep-0001/)">https://peps.python.org/pep-0001/)</a>, 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.</span> | |
| <span class="Special">#</span><span class="Title"> Rejected Ideas</span> | |
| <span class="htmlItalic"><a name="rejected-ideas"></a></span> | |
| <span class="Special">##</span><span class="Title"> Acceptance without reference implementation</span> | |
| <span class="htmlItalic"><a name="acceptance-without-reference-implementation"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> ASCII encoding</span> | |
| <span class="htmlItalic"><a name="ascii-encoding"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special DiffChange">##</span><span class="Title DiffChange"> </span><span class="Title DiffText">Imm</span><span class="Title DiffChange">utability of PHEPs</span><span class="DiffChange"> </span> | |
| <span class="htmlItalic"><a name="immutability-of-pheps"></a></span> | |
| <span class="htmlItalic DiffText">As currently written, PHEPs are laregly [immutable](#phep-maintenance) once Final. Substantive changes require</span><span class="htmlItalic DiffChange"> 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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">The possible approaches that emerged from discussion roughly span the range:</span><span class="DiffAdd"> </span> | |
| <span class="Statement DiffText">1.</span><span class="htmlItalic DiffText"> 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</span><span class="htmlItalic DiffChange">.</span> | |
| <span class="Statement DiffAdd">2.</span><span class="htmlItalic DiffAdd"> Allowing non-substantive changes to be undertaken without community review; PHEP-1 is written to this standard.</span> | |
| <span class="Statement DiffAdd">3.</span><span class="htmlItalic DiffAdd"> Allowing some level of substantive change with potentially more streamlined review, without drafting a new PHEP. This is perhaps the most flexible approach.</span> | |
| <span class="htmlItalic DiffChange">On</span><span class="htmlItalic DiffText">e 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</span><span class="htmlItalic DiffChange">.</span> | |
| <span class="Special">##</span><span class="Title"> Quorum requirement</span> | |
| <span class="htmlItalic"><a name="quorum-requirement"></a></span> | |
| <span class="htmlItalic">The [resolution process](#phep-review-resolution) does not require a quorum for a vote. Suggested quorum requirements included:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring "substantial community representation" at a vote.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring representation from at least one core package at a vote.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Objections may be raised in the PR, so nobody need be present to break consensus for acceptance.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The minimum one-month notice before the meeting allows objections to be raised.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic">As consensus is required, any of these "nays" carry the vote.</span> | |
| <span class="htmlItalic DiffAdd">The recommendation that the author of the PHEP be present for the [vote](#phep-review-resolution) came out of quorum discussions.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Special">##</span><span class="Title"> Recording names at acceptance</span> | |
| <span class="htmlItalic"><a name="recording-names-at-acceptance"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> Source formatting</span> | |
| <span class="htmlItalic"><a name="source-formatting"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Open Issues</span> | |
| <span class="htmlItalic"><a name="open-issues"></a></span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="htmlItalic">There are no remaining open issues.</span> | |
| <span class="Special DiffAdd">#</span><span class="Title DiffAdd"> Revisions</span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">Revision 1 (pending): Initial approval.</span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Special">#</span><span class="Title"> Copyright</span> | |
| <span class="htmlItalic"><a name="copyright"></a></span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">@techreport(phep1,</span> | |
| <span class="htmlItalic"> author = {Jonathan T. Niehof},</span> | |
| <span class="htmlItalic"> title = {PHEP Purpose and Guidelines},</span> | |
| <span class="DiffChange"> year = {2023</span><span class="DiffText">--2024</span><span class="DiffChange">},</span><span class="DiffChange"> </span> | |
| type = {PHEP}, | |
| <span class="htmlItalic"> number = {1},</span> | |
| doi = {10.5281/zenodo.xxxxxxx} | |
| <span class="htmlItalic">)</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">This document draws from:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://peps.python.org/pep-0001/">https://peps.python.org/pep-0001/</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://numpy.org/neps/nep-0000.html">https://numpy.org/neps/nep-0000.html</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md">https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md</a>></span> | |
| </pre> | |
| </div></td> | |
| </tr> | |
| </table> | |
| </body> | |
| </html> | |
| <!-- vim: set foldmethod=manual : --> | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <meta charset="UTF-8"> | |
| <title>diff</title> | |
| <meta name="Generator" content="Vim/8.2"> | |
| <meta name="plugin-version" content="vim8.1_v2"> | |
| <meta name="settings" content="whole_filler,use_css,pre_wrap,no_foldcolumn,prevent_copy=,use_input_for_pc=fallback"> | |
| <meta name="colorscheme" content="none"> | |
| <style> | |
| <!-- | |
| pre { white-space: pre-wrap; font-family: monospace; color: #000000; background-color: #ffffff; } | |
| body { font-family: monospace; color: #000000; background-color: #ffffff; } | |
| * { font-size: 1em; } | |
| .Identifier { color: #008080; } | |
| .Statement { color: #af5f00; } | |
| .Constant { color: #c00000; } | |
| .htmlItalic { font-style: italic; } | |
| .Title { color: #c000c0; } | |
| .Underlined { color: #c000c0; text-decoration: underline; } | |
| .htmlBold { font-weight: bold; } | |
| .Type { color: #008000; } | |
| .Special { color: #c000c0; } | |
| .DiffAdd { background-color: #5fd7ff; padding-bottom: 1px; } | |
| .DiffChange { background-color: #ffd7ff; padding-bottom: 1px; } | |
| .DiffDelete { color: #8080ff; background-color: #afffff; padding-bottom: 1px; } | |
| .DiffText { background-color: #ff6060; padding-bottom: 1px; font-weight: bold; } | |
| --> | |
| <!-- | |
| table { table-layout: fixed; } | |
| html, body, table, tbody { width: 100%; margin: 0; padding: 0; } | |
| table, td, th { border: 1px solid; } | |
| td { vertical-align: top; } | |
| th, td { width: 50.0%; } | |
| td div { overflow: auto; } | |
| --> | |
| </style> | |
| </head> | |
| <body> | |
| <table id='vimCodeElement'> | |
| <tr> | |
| <th>./seventh_pr.md</th> | |
| <th>phep-0001.md</th> | |
| </tr><tr> | |
| <td><div> | |
| <pre> | |
| <span class="Special">```</span> | |
| PHEP: 1 | |
| Title: PHEP Purpose and Guidelines | |
| Author: Jonathan T. Niehof <jtniehof@gmail.com> <<a href="https://orcid.org/0000-0001-6286-5809">https://orcid.org/0000-0001-6286-5809</a>> | |
| Discussions-To: <a href="https://github.com/heliophysicsPy/standards/pull/22">https://github.com/heliophysicsPy/standards/pull/22</a> | |
| Revision: 1 | |
| Status: Draft | |
| Type: Process | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| Created: 20-Oct-2023 | |
| <span class="DiffChange">Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024</span> | |
| <span class="Special">```</span> | |
| <span class="Special">#</span><span class="Title"> What is a PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-is-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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, 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 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 [<span class="Underlined">on GitHub</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>). | |
| <span class="Special">#</span><span class="Title"> PHEP Motivation</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-motivation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>) 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Audience</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-audience"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Types</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-type"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| There are three types of PHEP: | |
| <span class="Statement">1.</span> A <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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 [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>). Examples include testing requirements, OS support, and dependency handling. | |
| <span class="Statement">2.</span> An <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> 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. | |
| <span class="Statement">3.</span> A <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Applicability</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-applicability"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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. | |
| <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. | |
| <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> 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 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 [<span class="Underlined">RFC2119</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a></span>); the use of <span class="Special">`</span>must<span class="Special">`</span>, <span class="Special">`</span>must not<span class="Special">`</span>, <span class="Special">`</span>should<span class="Special">`</span>, and <span class="Special">`</span>should not<span class="Special">`</span> are preferred. | |
| <span class="Special">#</span><span class="Title"> PHEP Workflow</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-workflow"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| All PHEP workflow is conducted via the [<span class="Underlined">GitHub PyHC standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Editors</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-editors"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">PHEP Editor Responsibilities & Workflow</span>](<span class="Constant">#phep-editor-responsibilities-workflow</span>) 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 <span class="Special">`</span>@heliophysicsPy/phep-editors<span class="Special">`</span> on GitHub. | |
| <span class="Special">##</span><span class="Title"> Start with an idea</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"start-with-an-idea"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">telecon</span>](<span class="Constant"><a href="https://heliopython.org/meetings/">https://heliopython.org/meetings/</a></span>), other established PyHC [<span class="Underlined">discussion channels</span>](<span class="Constant"><a href="https://heliopython.org/contact/">https://heliopython.org/contact/</a></span>) including the email list or Matrix/Slack, and [<span class="Underlined">an issue in the standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/issues/new/choose">https://github.com/heliophysicsPy/standards/issues/new/choose</a></span>) (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. | |
| 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 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. | |
| <span class="Special">##</span><span class="Title"> Submitting a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"submitting-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The proposal must be submitted as a draft PHEP via a [<span class="Underlined">GitHub pull request</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/pulls">https://github.com/heliophysicsPy/standards/pulls</a></span>). The draft must be written in PHEP style as described below. The editors may correct minor errors. | |
| The standard PHEP workflow is: | |
| <span class="Statement">*</span> You, the PHEP author, fork the PyHC [<span class="Underlined">standards</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>) repository, and create a file named <span class="Special">`</span>phep-9999.md<span class="Special">`</span> that contains your new PHEP. Use "9999" as your draft PHEP number. | |
| <span class="Statement">*</span> In the "Type:" header field, enter "Standards Track", "Informational", or "Process" as appropriate, and for the "Status:" field enter "Draft". For full details, see [<span class="Underlined">PHEP Header Preamble</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">*</span> Push this to a branch (not <span class="Special">`</span>main<span class="Special">`</span>) 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. | |
| <span class="Statement">*</span> The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: | |
| <span class="Statement"> *</span> It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. | |
| <span class="Statement"> *</span> It is of reasonable scope, not too broad or unfocused. | |
| <span class="Statement"> *</span> The title accurately describes the content. | |
| <span class="Statement"> *</span> 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. | |
| If the PHEP isn't ready for approval, an editor will send it back to the author with specific instructions. | |
| <span class="Statement">*</span> 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 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. | |
| <span class="Special">##</span><span class="Title"> Discussing a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"discussing-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 <span class="Special">`</span>Discussions-To<span class="Special">`</span> 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 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 <span class="Special">`</span>Post-History<span class="Special">`</span> 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. | |
| 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 <span class="Special">`</span>Discussions-To<span class="Special">`</span> link must be updated, and the new PR discussion should link to the old for reference. | |
| PHEP discussions are subject to the [<span class="Underlined">PyHC Code of Conduct</span>](<span class="Constant"><a href="https://heliopython.org/docs/code_of_conduct/">https://heliopython.org/docs/code_of_conduct/</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Review & Resolution</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-review-resolution"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">discussion</span>](<span class="Constant">#discussing-a-phep</span>) 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, 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 <span class="htmlItalic">*</span><span class="htmlItalic">after</span><span class="htmlItalic">*</span> 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. | |
| "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.) | |
| 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, [<span class="Underlined">transfer it to another author</span>](<span class="Constant">transferring-phep-ownership</span>), 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. 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. | |
| <span class="DiffChange">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 dat</span><span class="DiffText">a</span><span class="DiffChange"> of acceptance, as appropriate. The editors must post announcements of PHEP resolution to the PyHC mailing list.</span> | |
| 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: | |
| ![<span class="Underlined">PHEP status flow diagram</span>](<span class="Constant">phep-0001/process_flow.svg</span>) | |
| Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors or author push a commit to the PR branch which: | |
| <span class="Statement">1.</span> Updates the Status appropriately. | |
| <span class="Statement">2.</span> Puts the current date in the Post-History header. | |
| <span class="Statement">3.</span> Updates the Revisions section with the date accepted or rejected, as appropriate. | |
| <span class="Statement">4.</span> Updates the copyright date as necessary. | |
| <span class="Statement DiffChange">6.</span><span class="DiffChange"> Updates the DOI in the citation with a new DOI that the editors have reserved</span> | |
| The editors merge the PR into <span class="Special">`</span>main<span class="Special">`</span> (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 <span class="Special">`</span>Replaced-By<span class="Special">`</span> field in its header updated (see [<span class="Underlined">PHEP Maintenance</span>](<span class="Constant">#phep-maintenance</span>)). | |
| The complete PHEP approval process is: | |
| ![<span class="Underlined">PHEP workflow diagram</span>](<span class="Constant">phep-0001/workflow.svg</span>) | |
| 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. | |
| <span class="Special">##</span><span class="Title"> PHEP Maintenance</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-maintenance"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 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: | |
| <span class="Statement">1.</span> A PHEP is Replaced due to acceptance of a new PHEP, requiring an update to the header. | |
| <span class="Statement">2.</span> A clear typo, misspelling, or other error not affecting the meaning of a PHEP is found. | |
| <span class="Statement">3.</span> 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: | |
| <span class="Statement">1.</span> The Revision header is incremented by one. | |
| <span class="Statement">2.</span> The Status is updated to Replaced and the Replaced-By header updated if a PHEP has been replaced. | |
| <span class="Statement">3.</span> The Post-History header is updated with the date of the new PR. | |
| <span class="Statement">4.</span> A new entry is added in the Revisions section, briefly explaining the changes and the need for them. | |
| <span class="Statement">5.</span> The copyright date is updated as necessary. | |
| <span class="Statement">6.</span> 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. | |
| <span class="Special">#</span><span class="Title"> What belongs in a successful PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-belongs-in-a-successful-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Statement">1.</span> <span class="htmlBold">**</span><span class="htmlBold">Preamble</span><span class="htmlBold">**</span> - [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style headers containing metadata about the PHEP, described [<span class="Underlined">below</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">2.</span> <span class="htmlBold">**</span><span class="htmlBold">Abstract</span><span class="htmlBold">**</span> - a short (~200 word) description of the issue being addressed. | |
| <span class="Statement">3.</span> <span class="htmlBold">**</span><span class="htmlBold">Motivation</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">4.</span> <span class="htmlBold">**</span><span class="htmlBold">Rationale</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">5.</span> <span class="htmlBold">**</span><span class="htmlBold">Specification</span><span class="htmlBold">**</span> - The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. | |
| <span class="Statement">6.</span> <span class="htmlBold">**</span><span class="htmlBold">Backwards Compatibility</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">7.</span> <span class="htmlBold">**</span><span class="htmlBold">Security Implications</span><span class="htmlBold">**</span> - Any security concerns should be explicitly written out. | |
| <span class="Statement">8.</span> <span class="htmlBold">**</span><span class="htmlBold">How to Teach This</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">9.</span> <span class="htmlBold">**</span><span class="htmlBold">Reference Implementation</span><span class="htmlBold">**</span> - 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). | |
| <span class="Statement">10.</span> <span class="htmlBold">**</span><span class="htmlBold">Rejected Ideas</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">11.</span> <span class="htmlBold">**</span><span class="htmlBold">Open Issues</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">12.</span> <span class="htmlBold">**</span><span class="htmlBold">Footnotes</span><span class="htmlBold">**</span> - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. | |
| <span class="Statement">13.</span> <span class="htmlBold">**</span><span class="htmlBold">Revisions</span><span class="htmlBold">**</span> - Brief summary of changes by revision number, including the date of approval. | |
| <span class="Statement DiffChange">14.</span><span class="DiffChange"> </span><span class="htmlBold DiffChange">**</span><span class="htmlBold DiffChange">Copyright/license</span><span class="htmlBold DiffChange">**</span><span class="DiffChange"> - Each new PHEP must be placed under a dual license of public domain and </span><span class="DiffChange">[</span><span class="Underlined DiffChange">CC0-1.0-Universal</span><span class="DiffChange">]</span><span class="DiffChange">(</span><span class="Constant DiffChange"><a href="https://creativecommons.org/publicdomain/zero/1.0/">https://creativecommons.org/publicdomain/zero/1.0/</a></span><span class="DiffChange">)</span><span class="DiffChange"> and include citation information (see this PHEP for an example).</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Formats and Templates</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-formats-and-templates"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">CommonMark specification</span>](<span class="Constant"><a href="https://spec.commonmark.org/">https://spec.commonmark.org/</a></span>) at the time the PHEP is approved. PHEPs must not use [<span class="Underlined">GitHub extensions</span>](<span class="Constant"><a href="https://github.github.com/gfm/">https://github.github.com/gfm/</a></span>). | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Header Preamble</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-header-preamble"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Each PHEP must begin with an [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style header preamble, marked off with a [<span class="Underlined">code fence</span>](<span class="Constant"><a href="https://spec.commonmark.org/current/#fenced-code-blocks">https://spec.commonmark.org/current/#fenced-code-blocks</a></span>). The headers must appear in the following order. Headers marked with "<span class="htmlItalic">*</span><span class="htmlItalic">" are optional. All other headers are required.</span> | |
| ``` | |
| PHEP: <phep number> | |
| Title: <phep title> | |
| Author: <list of authors' real names; optionally, email addrs and/or ORCIDs> | |
| Discussions-To: <URL of current PR> | |
| Revision: <phep version number> | |
| Status: <Draft | Rejected | Withdrawn | Final | Replaced> | |
| Type: <Standards Track | Informational | Process> | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| <span class="Statement"> *</span><span class="htmlItalic"> Requires: <phep numbers></span> | |
| Created: <date created on, in dd-mmm-yyyy format> | |
| Post-History: <dates, in dd-mmm-yyyy format> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaces: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaced-By: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Resolution: <url></span> | |
| ``` | |
| <span class="htmlItalic">The Author header lists the names and optionally the email addresses and/or [ORCIDs](<a href="https://orcid.org)">https://orcid.org)</a> of all the authors of the PHEP. The format of the Author header values must be:</span> | |
| <span class="htmlItalic">`Random J. User <random@example.com> <<a href="https://orcid.org/0000-0000-0000-0000">https://orcid.org/0000-0000-0000-0000</a>>`</span> | |
| <span class="htmlItalic">if the email address and ORCID are included, and just:</span> | |
| <span class="htmlItalic">`Random J. User`</span> | |
| <span class="htmlItalic">for just the name (similarly for ORCID without email address and vice versa).</span> | |
| <span class="htmlItalic">If there are multiple authors, each should be on a separate line following [RFC 2822](<a href="https://datatracker.ietf.org/doc/html/rfc2822.html)">https://datatracker.ietf.org/doc/html/rfc2822.html)</a> continuation line conventions.</span> | |
| <span class="htmlItalic">The Discussions-To header provides the URL to the current PR discussion thread for the PHEP.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">The Type header specifies the [type](#phep-type) of PHEP: Standards Track, Informational, or Process.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP depends on.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Auxiliary Files</span> | |
| <span class="htmlItalic"><a name="auxiliary-files"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Transferring PHEP Ownership</span> | |
| <span class="htmlItalic"><a name="transferring-phep-ownership"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Editor Responsibilities & Workflow</span> | |
| <span class="htmlItalic"><a name="phep-editor-responsibilities-workflow"></a></span> | |
| <span class="htmlItalic">A PHEP editor must be added to the `@heliophysicsPy/phep-editors` group on GitHub and must watch the `standards` repository.</span> | |
| <span class="htmlItalic">For each new PHEP that comes in, an editor does the following:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The title should accurately describe the content.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The PHEP's type is correctly labeled ("Standards Track", "Informational", or "Process"), and its status is "Draft".</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The file name extension is correct (i.e. `.md`).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic">If the PHEP isn't ready, an editor will send it back to the author for updates, with specific instructions.</span> | |
| <span class="htmlItalic">Once the PHEP is ready for discussion, a PHEP editor will:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Assign a PHEP number (almost always the next available number).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Ask the author to update the PHEP with the PR link, mark the PR ready for review, and post an announcement.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP 1 Acceptance</span> | |
| <span class="htmlItalic"><a name="phep-1-acceptance"></a></span> | |
| <span class="htmlItalic">This PHEP is subject to the same review and acceptance process that it proposes.</span> | |
| <span class="Special">#</span><span class="Title"> Rationale</span> | |
| <span class="htmlItalic"><a name="rationale"></a></span> | |
| <span class="htmlItalic">PHEP 1 is based on [PEP 1](<a href="https://peps.python.org/pep-0001/)">https://peps.python.org/pep-0001/)</a>, 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.</span> | |
| <span class="Special">#</span><span class="Title"> Rejected Ideas</span> | |
| <span class="htmlItalic"><a name="rejected-ideas"></a></span> | |
| <span class="Special">##</span><span class="Title"> Acceptance without reference implementation</span> | |
| <span class="htmlItalic"><a name="acceptance-without-reference-implementation"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> ASCII encoding</span> | |
| <span class="htmlItalic"><a name="ascii-encoding"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Special">##</span><span class="Title"> Quorum requirement</span> | |
| <span class="htmlItalic"><a name="quorum-requirement"></a></span> | |
| <span class="htmlItalic">The [resolution process](#phep-review-resolution) does not require a quorum for a vote. Suggested quorum requirements included:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring "substantial community representation" at a vote.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring representation from at least one core package at a vote.</span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Objections may be raised in the PR, so nobody need be present to break consensus for acceptance.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The minimum one-month notice before the meeting allows objections to be raised.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic">As consensus is required, any of these "nays" carry the vote.</span> | |
| <span class="htmlItalic">The recommendation that the author of the PHEP be present for the [vote](#phep-review-resolution) came out of quorum discussions.</span> | |
| <span class="Special">##</span><span class="Title"> Recording names at acceptance</span> | |
| <span class="htmlItalic"><a name="recording-names-at-acceptance"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> Source formatting</span> | |
| <span class="htmlItalic"><a name="source-formatting"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Open Issues</span> | |
| <span class="htmlItalic"><a name="open-issues"></a></span> | |
| <span class="DiffChange"> </span><span class="DiffChange"> </span> | |
| <span class="Special DiffAdd">##</span><span class="Title DiffAdd"> Mutability of PHEPs</span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd"><a name="immutability-of-pheps"></a></span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">On the downside, immutability discourages very small but potentially useful changes. It could make more work by requiring submission of a new PHEP.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">From the immutability discussion, a process was introduced for making very small changes, such as fixing typos.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">The possible approaches that emerged from discussion roughly span the range:</span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Statement DiffAdd">1.</span><span class="htmlItalic DiffAdd"> 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.</span> | |
| <span class="Statement DiffAdd">2.</span><span class="htmlItalic DiffAdd"> Allowing non-substantive changes to be undertaken without community review; PHEP-1 is currently written to this standard.</span> | |
| <span class="Statement DiffAdd">3.</span><span class="htmlItalic DiffAdd"> Further allowing some level of substantive change with potentially more streamlined review, without drafting a new PHEP. This is perhaps the most flexible approach.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="Special">#</span><span class="Title"> Revisions</span> | |
| <span class="htmlItalic">Revision 1 (pending): Initial approval.</span> | |
| <span class="Special">#</span><span class="Title"> Copyright</span> | |
| <span class="htmlItalic"><a name="copyright"></a></span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">@techreport(phep1,</span> | |
| <span class="htmlItalic"> author = {Jonathan T. Niehof},</span> | |
| <span class="htmlItalic"> title = {PHEP Purpose and Guidelines},</span> | |
| year = {2023--2024}, | |
| type = {PHEP}, | |
| <span class="htmlItalic"> number = {1},</span> | |
| doi = {10.5281/zenodo.xxxxxxx} | |
| <span class="htmlItalic">)</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">This document draws from:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://peps.python.org/pep-0001/">https://peps.python.org/pep-0001/</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://numpy.org/neps/nep-0000.html">https://numpy.org/neps/nep-0000.html</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md">https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md</a>></span> | |
| </pre> | |
| </div></td> | |
| <td><div> | |
| <pre> | |
| <span class="Special">```</span> | |
| PHEP: 1 | |
| Title: PHEP Purpose and Guidelines | |
| Author: Jonathan T. Niehof <jtniehof@gmail.com> <<a href="https://orcid.org/0000-0001-6286-5809">https://orcid.org/0000-0001-6286-5809</a>> | |
| Discussions-To: <a href="https://github.com/heliophysicsPy/standards/pull/22">https://github.com/heliophysicsPy/standards/pull/22</a> | |
| Revision: 1 | |
| Status: Draft | |
| Type: Process | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| Created: 20-Oct-2023 | |
| <span class="DiffChange">Post-History: 24-Oct-2023, 31-Oct-2023, 09-Nov-2023, 27-Nov-2023, 06-Dec-2023, 14-Dec-2023, 07-Feb-2024</span><span class="DiffText">, 28-Feb-2024</span> | |
| <span class="Special">```</span> | |
| <span class="Special">#</span><span class="Title"> What is a PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-is-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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, 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 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 [<span class="Underlined">on GitHub</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>). | |
| <span class="Special">#</span><span class="Title"> PHEP Motivation</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-motivation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>) 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Audience</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-audience"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Types</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-type"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| There are three types of PHEP: | |
| <span class="Statement">1.</span> A <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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 [<span class="Underlined">PyHC standards</span>](<span class="Constant"><a href="https://doi.org/10.5281/zenodo.2529131">https://doi.org/10.5281/zenodo.2529131</a></span>). Examples include testing requirements, OS support, and dependency handling. | |
| <span class="Statement">2.</span> An <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> 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. | |
| <span class="Statement">3.</span> A <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Applicability</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-applicability"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="htmlBold">**</span><span class="htmlBold">Standards</span><span class="htmlBold">**</span> 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. | |
| <span class="htmlBold">**</span><span class="htmlBold">Informational</span><span class="htmlBold">**</span> PHEPs are for the benefit of PyHC developers and users and may represent "best practices". They are not binding. | |
| <span class="htmlBold">**</span><span class="htmlBold">Process</span><span class="htmlBold">**</span> 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 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 [<span class="Underlined">RFC2119</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a></span>); the use of <span class="Special">`</span>must<span class="Special">`</span>, <span class="Special">`</span>must not<span class="Special">`</span>, <span class="Special">`</span>should<span class="Special">`</span>, and <span class="Special">`</span>should not<span class="Special">`</span> are preferred. | |
| <span class="Special">#</span><span class="Title"> PHEP Workflow</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-workflow"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| All PHEP workflow is conducted via the [<span class="Underlined">GitHub PyHC standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Editors</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-editors"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">PHEP Editor Responsibilities & Workflow</span>](<span class="Constant">#phep-editor-responsibilities-workflow</span>) 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 <span class="Special">`</span>@heliophysicsPy/phep-editors<span class="Special">`</span> on GitHub. | |
| <span class="Special">##</span><span class="Title"> Start with an idea</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"start-with-an-idea"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">telecon</span>](<span class="Constant"><a href="https://heliopython.org/meetings/">https://heliopython.org/meetings/</a></span>), other established PyHC [<span class="Underlined">discussion channels</span>](<span class="Constant"><a href="https://heliopython.org/contact/">https://heliopython.org/contact/</a></span>) including the email list or Matrix/Slack, and [<span class="Underlined">an issue in the standards repository</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/issues/new/choose">https://github.com/heliophysicsPy/standards/issues/new/choose</a></span>) (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. | |
| 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 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. | |
| <span class="Special">##</span><span class="Title"> Submitting a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"submitting-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The proposal must be submitted as a draft PHEP via a [<span class="Underlined">GitHub pull request</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards/pulls">https://github.com/heliophysicsPy/standards/pulls</a></span>). The draft must be written in PHEP style as described below. The editors may correct minor errors. | |
| The standard PHEP workflow is: | |
| <span class="Statement">*</span> You, the PHEP author, fork the PyHC [<span class="Underlined">standards</span>](<span class="Constant"><a href="https://github.com/heliophysicsPy/standards">https://github.com/heliophysicsPy/standards</a></span>) repository, and create a file named <span class="Special">`</span>phep-9999.md<span class="Special">`</span> that contains your new PHEP. Use "9999" as your draft PHEP number. | |
| <span class="Statement">*</span> In the "Type:" header field, enter "Standards Track", "Informational", or "Process" as appropriate, and for the "Status:" field enter "Draft". For full details, see [<span class="Underlined">PHEP Header Preamble</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">*</span> Push this to a branch (not <span class="Special">`</span>main<span class="Special">`</span>) 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. | |
| <span class="Statement">*</span> The PHEP editors review your PR for structure, formatting, and other errors. Approval criteria are: | |
| <span class="Statement"> *</span> It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted. | |
| <span class="Statement"> *</span> It is of reasonable scope, not too broad or unfocused. | |
| <span class="Statement"> *</span> The title accurately describes the content. | |
| <span class="Statement"> *</span> 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. | |
| If the PHEP isn't ready for approval, an editor will send it back to the author with specific instructions. | |
| <span class="Statement">*</span> 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 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. | |
| <span class="Special">##</span><span class="Title"> Discussing a PHEP</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"discussing-a-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 <span class="Special">`</span>Discussions-To<span class="Special">`</span> 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 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 <span class="Special">`</span>Post-History<span class="Special">`</span> 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. | |
| 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 <span class="Special">`</span>Discussions-To<span class="Special">`</span> link must be updated, and the new PR discussion should link to the old for reference. | |
| PHEP discussions are subject to the [<span class="Underlined">PyHC Code of Conduct</span>](<span class="Constant"><a href="https://heliopython.org/docs/code_of_conduct/">https://heliopython.org/docs/code_of_conduct/</a></span>). | |
| <span class="Special">##</span><span class="Title"> PHEP Review & Resolution</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-review-resolution"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">discussion</span>](<span class="Constant">#discussing-a-phep</span>) 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, 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 <span class="htmlItalic">*</span><span class="htmlItalic">after</span><span class="htmlItalic">*</span> 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. | |
| "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.) | |
| 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, [<span class="Underlined">transfer it to another author</span>](<span class="Constant">transferring-phep-ownership</span>), 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. 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. | |
| <span class="DiffChange">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 dat</span><span class="DiffText">e</span><span class="DiffChange"> of acceptance, as appropriate. The editors must post announcements of PHEP resolution to the PyHC mailing list.</span> | |
| 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: | |
| ![<span class="Underlined">PHEP status flow diagram</span>](<span class="Constant">phep-0001/process_flow.svg</span>) | |
| Upon reaching "Final", "Withdrawn", or "Rejected" status, the editors or author push a commit to the PR branch which: | |
| <span class="Statement">1.</span> Updates the Status appropriately. | |
| <span class="Statement">2.</span> Puts the current date in the Post-History header. | |
| <span class="Statement">3.</span> Updates the Revisions section with the date accepted or rejected, as appropriate. | |
| <span class="Statement">4.</span> Updates the copyright date as necessary. | |
| <span class="Statement DiffChange">6.</span><span class="DiffChange"> Updates the DOI in the citation with a new DOI that the editors have reserved</span><span class="DiffText">.</span> | |
| The editors merge the PR into <span class="Special">`</span>main<span class="Special">`</span> (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 <span class="Special">`</span>Replaced-By<span class="Special">`</span> field in its header updated (see [<span class="Underlined">PHEP Maintenance</span>](<span class="Constant">#phep-maintenance</span>)). | |
| The complete PHEP approval process is: | |
| ![<span class="Underlined">PHEP workflow diagram</span>](<span class="Constant">phep-0001/workflow.svg</span>) | |
| 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. | |
| <span class="Special">##</span><span class="Title"> PHEP Maintenance</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-maintenance"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 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: | |
| <span class="Statement">1.</span> A PHEP is Replaced due to acceptance of a new PHEP, requiring an update to the header. | |
| <span class="Statement">2.</span> A clear typo, misspelling, or other error not affecting the meaning of a PHEP is found. | |
| <span class="Statement">3.</span> 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: | |
| <span class="Statement">1.</span> The Revision header is incremented by one. | |
| <span class="Statement">2.</span> The Status is updated to Replaced and the Replaced-By header updated if a PHEP has been replaced. | |
| <span class="Statement">3.</span> The Post-History header is updated with the date of the new PR. | |
| <span class="Statement">4.</span> A new entry is added in the Revisions section, briefly explaining the changes and the need for them. | |
| <span class="Statement">5.</span> The copyright date is updated as necessary. | |
| <span class="Statement">6.</span> 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. | |
| <span class="Special">#</span><span class="Title"> What belongs in a successful PHEP?</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"what-belongs-in-a-successful-phep"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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. | |
| <span class="Statement">1.</span> <span class="htmlBold">**</span><span class="htmlBold">Preamble</span><span class="htmlBold">**</span> - [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style headers containing metadata about the PHEP, described [<span class="Underlined">below</span>](<span class="Constant">#phep-header-preamble</span>). | |
| <span class="Statement">2.</span> <span class="htmlBold">**</span><span class="htmlBold">Abstract</span><span class="htmlBold">**</span> - a short (~200 word) description of the issue being addressed. | |
| <span class="Statement">3.</span> <span class="htmlBold">**</span><span class="htmlBold">Motivation</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">4.</span> <span class="htmlBold">**</span><span class="htmlBold">Rationale</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">5.</span> <span class="htmlBold">**</span><span class="htmlBold">Specification</span><span class="htmlBold">**</span> - The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. | |
| <span class="Statement">6.</span> <span class="htmlBold">**</span><span class="htmlBold">Backwards Compatibility</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">7.</span> <span class="htmlBold">**</span><span class="htmlBold">Security Implications</span><span class="htmlBold">**</span> - Any security concerns should be explicitly written out. | |
| <span class="Statement">8.</span> <span class="htmlBold">**</span><span class="htmlBold">How to Teach This</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">9.</span> <span class="htmlBold">**</span><span class="htmlBold">Reference Implementation</span><span class="htmlBold">**</span> - 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). | |
| <span class="Statement">10.</span> <span class="htmlBold">**</span><span class="htmlBold">Rejected Ideas</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">11.</span> <span class="htmlBold">**</span><span class="htmlBold">Open Issues</span><span class="htmlBold">**</span> - 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. | |
| <span class="Statement">12.</span> <span class="htmlBold">**</span><span class="htmlBold">Footnotes</span><span class="htmlBold">**</span> - A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. | |
| <span class="Statement">13.</span> <span class="htmlBold">**</span><span class="htmlBold">Revisions</span><span class="htmlBold">**</span> - Brief summary of changes by revision number, including the date of approval. | |
| <span class="Statement DiffChange">14.</span><span class="DiffChange"> </span><span class="htmlBold DiffChange">**</span><span class="htmlBold DiffChange">Copyright/license</span><span class="htmlBold DiffChange">**</span><span class="DiffChange"> - Each new PHEP must be placed under a dual license of public domain and </span><span class="DiffChange">[</span><span class="Underlined DiffChange">CC0-1.0-Universal</span><span class="DiffChange">]</span><span class="DiffChange">(</span><span class="Constant DiffChange"><a href="https://creativecommons.org/publicdomain/zero/1.0/">https://creativecommons.org/publicdomain/zero/1.0/</a></span><span class="DiffChange">)</span><span class="DiffChange"> and include citation information (see this PHEP for an example).</span><span class="DiffText"> 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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Formats and Templates</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-formats-and-templates"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| 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 [<span class="Underlined">CommonMark specification</span>](<span class="Constant"><a href="https://spec.commonmark.org/">https://spec.commonmark.org/</a></span>) at the time the PHEP is approved. PHEPs must not use [<span class="Underlined">GitHub extensions</span>](<span class="Constant"><a href="https://github.github.com/gfm/">https://github.github.com/gfm/</a></span>). | |
| 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. | |
| <span class="Special">#</span><span class="Title"> PHEP Header Preamble</span> | |
| <span class="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"phep-header-preamble"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Each PHEP must begin with an [<span class="Underlined">RFC 2822</span>](<span class="Constant"><a href="https://datatracker.ietf.org/doc/html/rfc2822.html">https://datatracker.ietf.org/doc/html/rfc2822.html</a></span>) style header preamble, marked off with a [<span class="Underlined">code fence</span>](<span class="Constant"><a href="https://spec.commonmark.org/current/#fenced-code-blocks">https://spec.commonmark.org/current/#fenced-code-blocks</a></span>). The headers must appear in the following order. Headers marked with "<span class="htmlItalic">*</span><span class="htmlItalic">" are optional. All other headers are required.</span> | |
| ``` | |
| PHEP: <phep number> | |
| Title: <phep title> | |
| Author: <list of authors' real names; optionally, email addrs and/or ORCIDs> | |
| Discussions-To: <URL of current PR> | |
| Revision: <phep version number> | |
| Status: <Draft | Rejected | Withdrawn | Final | Replaced> | |
| Type: <Standards Track | Informational | Process> | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| <span class="Statement"> *</span><span class="htmlItalic"> Requires: <phep numbers></span> | |
| Created: <date created on, in dd-mmm-yyyy format> | |
| Post-History: <dates, in dd-mmm-yyyy format> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaces: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Replaced-By: <phep number></span> | |
| <span class="Statement"> *</span><span class="htmlItalic"> Resolution: <url></span> | |
| ``` | |
| <span class="htmlItalic">The Author header lists the names and optionally the email addresses and/or [ORCIDs](<a href="https://orcid.org)">https://orcid.org)</a> of all the authors of the PHEP. The format of the Author header values must be:</span> | |
| <span class="htmlItalic">`Random J. User <random@example.com> <<a href="https://orcid.org/0000-0000-0000-0000">https://orcid.org/0000-0000-0000-0000</a>>`</span> | |
| <span class="htmlItalic">if the email address and ORCID are included, and just:</span> | |
| <span class="htmlItalic">`Random J. User`</span> | |
| <span class="htmlItalic">for just the name (similarly for ORCID without email address and vice versa).</span> | |
| <span class="htmlItalic">If there are multiple authors, each should be on a separate line following [RFC 2822](<a href="https://datatracker.ietf.org/doc/html/rfc2822.html)">https://datatracker.ietf.org/doc/html/rfc2822.html)</a> continuation line conventions.</span> | |
| <span class="htmlItalic">The Discussions-To header provides the URL to the current PR discussion thread for the PHEP.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">The Type header specifies the [type](#phep-type) of PHEP: Standards Track, Informational, or Process.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">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`.</span> | |
| <span class="htmlItalic">PHEPs may have a Requires header, indicating the PHEP numbers that this PHEP depends on.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Auxiliary Files</span> | |
| <span class="htmlItalic"><a name="auxiliary-files"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Transferring PHEP Ownership</span> | |
| <span class="htmlItalic"><a name="transferring-phep-ownership"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP Editor Responsibilities & Workflow</span> | |
| <span class="htmlItalic"><a name="phep-editor-responsibilities-workflow"></a></span> | |
| <span class="htmlItalic">A PHEP editor must be added to the `@heliophysicsPy/phep-editors` group on GitHub and must watch the `standards` repository.</span> | |
| <span class="htmlItalic">For each new PHEP that comes in, an editor does the following:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The title should accurately describe the content.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The PHEP's type is correctly labeled ("Standards Track", "Informational", or "Process"), and its status is "Draft".</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The file name extension is correct (i.e. `.md`).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic">If the PHEP isn't ready, an editor will send it back to the author for updates, with specific instructions.</span> | |
| <span class="htmlItalic">Once the PHEP is ready for discussion, a PHEP editor will:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Assign a PHEP number (almost always the next available number).</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Ask the author to update the PHEP with the PR link, mark the PR ready for review, and post an announcement.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> PHEP 1 Acceptance</span> | |
| <span class="htmlItalic"><a name="phep-1-acceptance"></a></span> | |
| <span class="htmlItalic">This PHEP is subject to the same review and acceptance process that it proposes.</span> | |
| <span class="Special">#</span><span class="Title"> Rationale</span> | |
| <span class="htmlItalic"><a name="rationale"></a></span> | |
| <span class="htmlItalic">PHEP 1 is based on [PEP 1](<a href="https://peps.python.org/pep-0001/)">https://peps.python.org/pep-0001/)</a>, 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.</span> | |
| <span class="Special">#</span><span class="Title"> Rejected Ideas</span> | |
| <span class="htmlItalic"><a name="rejected-ideas"></a></span> | |
| <span class="Special">##</span><span class="Title"> Acceptance without reference implementation</span> | |
| <span class="htmlItalic"><a name="acceptance-without-reference-implementation"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> ASCII encoding</span> | |
| <span class="htmlItalic"><a name="ascii-encoding"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special DiffAdd">##</span><span class="Title DiffAdd"> Immutability of PHEPs</span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd"><a name="immutability-of-pheps"></a></span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">The possible approaches that emerged from discussion roughly span the range:</span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Statement DiffAdd">1.</span><span class="htmlItalic DiffAdd"> 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.</span> | |
| <span class="Statement DiffAdd">2.</span><span class="htmlItalic DiffAdd"> Allowing non-substantive changes to be undertaken without community review; PHEP-1 is written to this standard.</span> | |
| <span class="Statement DiffAdd">3.</span><span class="htmlItalic DiffAdd"> Allowing some level of substantive change with potentially more streamlined review, without drafting a new PHEP. This is perhaps the most flexible approach.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="htmlItalic DiffAdd">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.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="Special">##</span><span class="Title"> Quorum requirement</span> | |
| <span class="htmlItalic"><a name="quorum-requirement"></a></span> | |
| <span class="htmlItalic">The [resolution process](#phep-review-resolution) does not require a quorum for a vote. Suggested quorum requirements included:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring "substantial community representation" at a vote.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Requiring representation from at least one core package at a vote.</span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> Objections may be raised in the PR, so nobody need be present to break consensus for acceptance.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> The minimum one-month notice before the meeting allows objections to be raised.</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> 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.</span> | |
| <span class="htmlItalic">As consensus is required, any of these "nays" carry the vote.</span> | |
| <span class="htmlItalic">The recommendation that the author of the PHEP be present for the [vote](#phep-review-resolution) came out of quorum discussions.</span> | |
| <span class="Special">##</span><span class="Title"> Recording names at acceptance</span> | |
| <span class="htmlItalic"><a name="recording-names-at-acceptance"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">##</span><span class="Title"> Source formatting</span> | |
| <span class="htmlItalic"><a name="source-formatting"></a></span> | |
| <span class="htmlItalic">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.</span> | |
| <span class="Special">#</span><span class="Title"> Open Issues</span> | |
| <span class="htmlItalic"><a name="open-issues"></a></span> | |
| <span class="htmlItalic DiffText">There are no remaining open issues.</span><span class="DiffChange"> </span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Special">#</span><span class="Title"> Revisions</span> | |
| <span class="htmlItalic">Revision 1 (pending): Initial approval.</span> | |
| <span class="Special">#</span><span class="Title"> Copyright</span> | |
| <span class="htmlItalic"><a name="copyright"></a></span> | |
| <span class="htmlItalic">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:</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">@techreport(phep1,</span> | |
| <span class="htmlItalic"> author = {Jonathan T. Niehof},</span> | |
| <span class="htmlItalic"> title = {PHEP Purpose and Guidelines},</span> | |
| year = {2023--2024}, | |
| type = {PHEP}, | |
| <span class="htmlItalic"> number = {1},</span> | |
| doi = {10.5281/zenodo.xxxxxxx} | |
| <span class="htmlItalic">)</span> | |
| <span class="htmlItalic">```</span> | |
| <span class="htmlItalic">This document draws from:</span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://peps.python.org/pep-0001/">https://peps.python.org/pep-0001/</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://numpy.org/neps/nep-0000.html">https://numpy.org/neps/nep-0000.html</a>></span> | |
| <span class="Statement">*</span><span class="htmlItalic"> <<a href="https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md">https://github.com/sunpy/sunpy-SEP/blob/master/SEP-0001.md</a>></span> | |
| </pre> | |
| </div></td> | |
| </tr> | |
| </table> | |
| </body> | |
| </html> | |
| <!-- vim: set foldmethod=manual : --> | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment