Created
February 28, 2024 15:02
-
-
Save jtniehof/c69cb18199d50361085b2086868e5544 to your computer and use it in GitHub Desktop.
Diffs of PHEP-0002
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; } | |
| .Constant { color: #c00000; } | |
| .Statement { color: #af5f00; } | |
| .Title { color: #c000c0; } | |
| .Underlined { color: #c000c0; text-decoration: underline; } | |
| .htmlBold { font-weight: bold; } | |
| .htmlItalic { font-style: italic; } | |
| .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>first_push.md</th> | |
| <th>phep-0002.md</th> | |
| </tr><tr> | |
| <td><div> | |
| <pre> | |
| <span class="Special">```</span> | |
| PHEP: 2 | |
| Title: PHEP Template | |
| 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/25">https://github.com/heliophysicsPy/standards/pull/25</a> | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| Status: Draft | |
| Type: Informational | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| Requires: 1 | |
| Created: 06-Dec-2023 | |
| <span class="DiffChange">Post-History: 06-Dec-2023</span><span class="DiffChange"> </span> | |
| <span class="Special">```</span> | |
| <span class="Special">#</span><span class="Title"> Abstract</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">"abstract"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| This PHEP provides a template to make it easier to write a PHEP-1 compliant PHEP. It does not establish or enforce any standard. Each section contains explanatory text for how to write that section in an actual PHEP. | |
| The majority of the text should be replaced with the text of your proposed PHEP. See [<span class="Underlined">Specification</span>](<span class="Constant">#specification</span>) for further directions on using this template. | |
| This section of your PHEP should include a short description of the issue being addressed. | |
| <span class="Special">#</span><span class="Title"> 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">"motivation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Discussions in the drafing of PHEP 1 indicated a desire to have a template to make it easier for potential PHEP writers to comply with the format, address the required elements, and avoid the "blank page" problem. | |
| 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. | |
| <span class="Special">#</span><span class="Title"> Rationale</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">"rationale"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The template model should help make the initial drafting of a PHEP a fairly simple copy-paste-replace operation. Although in theory any PHEP could be taken as a template, each PHEP is unique and it is easier to have one that spans the set of expected sections, while minimizing additional information. | |
| 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="Special">#</span><span class="Title"> Specification</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">"specification"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Use this PHEP by copying it to a new file, usually named <span class="Special">`</span>phep-9999.md<span class="Special">`</span>, and editing it. (See PHEP 1 for details on the process.) The text is in Markdown (specifically [<span class="Underlined">CommonMark</span>](<span class="Constant"><a href="https://spec.commonmark.org/">https://spec.commonmark.org/</a></span>)) and can be directly edited by any text editor. You can check the rendering of text fragments [<span class="Underlined">here</span>](<span class="Constant"><a href="https://spec.commonmark.org/dingus/">https://spec.commonmark.org/dingus/</a></span>), and editors with explicit Markdown support include: | |
| <span class="Statement">*</span> [<span class="Underlined">ReText</span>](<span class="Constant"><a href="https://github.com/retext-project/retext">https://github.com/retext-project/retext</a></span>) | |
| <span class="Statement">*</span> [<span class="Underlined">PyCharm</span>](<span class="Constant"><a href="https://www.jetbrains.com/help/pycharm/markdown.html">https://www.jetbrains.com/help/pycharm/markdown.html</a></span>) | |
| Start by updating the preamble as follows: | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">PHEP</span><span class="htmlBold">**</span> number should be 9999 until a new number is assigned by the editors. | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Author</span><span class="htmlBold">**</span> should be updated with your name and (ideally) email address and ORCID. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Discussions-To</span><span class="htmlBold">**</span> is the URL of your pull request once it is opened (so this usually is not updated until the PR is open). | |
| <span class="DiffDelete">--------------------------------------------------------------------------------</span> | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Status</span><span class="htmlBold">**</span> is Draft. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Type</span><span class="htmlBold">**</span> is "Standards Track" if proposing a requirement for PyHC packages; "Informational" for best practices and similar information; "Process" if proposing a means by which PyHC conducts itself (see PHEP 1). | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Content-Type</span><span class="htmlBold">**</span> must remain, verbatim <span class="Special">`</span>text/markdown; charset=UTF-8; variant=CommonMark<span class="Special">`</span>. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Requires</span><span class="htmlBold">**</span> should list the number of all PHEPs that this one depends on (i.e., that this one does not make sense without). Leave the header out if there are none. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Created</span><span class="htmlBold">**</span> is the date the PHEP was <span class="htmlItalic">*</span><span class="htmlItalic">assigned a number</span><span class="htmlItalic">*</span> by the editors. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Post-History</span><span class="htmlBold">**</span> should include the date of the first push to the PR (and subsequent pushes separated by commas) in <span class="Special">`</span>dd-mmm-yyyy<span class="Special">`</span>. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Replaces</span><span class="htmlBold">**</span> should be the number of a final PHEP which this PHEP proposes to replace, if appropriate (otherwise exclude this header). | |
| Now go through each section and fill it in with the contents of your PHEP, removing the text of this one as you go. Each section usually contains two parts. First is the relevant content for this template PHEP (if necessary). This is followed by the information that your PHEP should have within that section. | |
| The sections are not all required (in fact, strictly, none are required), but the information should be there. The author should use whatever means of organization seems appropriate, including deleting or consolidating sections, breaking sections into multiple sections, and using subsections. It is recommended to add HTML anchors after each heading to make linking easier in the future. | |
| The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. | |
| <span class="Special">#</span><span class="Title"> Backwards Compatibility</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">"backwards-compatibility"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| As the PHEP process is new, this template PHEP introduces no compatibility concerns. | |
| 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. If there are none, an explicit statement that there are no backward incompatibilities is preferred to removing the section. | |
| <span class="Special">#</span><span class="Title"> Security Implications</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">"security-implications"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| This PHEP raises no security implications as it does not interact with any executing code. | |
| Any security concerns should be explicitly written out; as with backwards compatibility, an explicit statement of no implications is preferred to removing the section. | |
| <span class="Special">#</span><span class="Title"> How to Teach This</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">"how-to-teach-this"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| This PHEP is, itself, meant as a teaching aid for PHEP 1. Demonstrating the process of using the template, e.g. as part of a PyHC telecon, may be appropriate. | |
| <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="Special">#</span><span class="Title"> Reference Implementation</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">"reference-implementation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| In a sense, this PHEP is itself a reference implementation. | |
| A reference implementation is not always necessary, but is strongly suggested for Standards Track PHEPs. In that case it would include a reference to an existing or new PyHC project which is compliant with the proposed standard and a description of how it complies. The description should point out where in the compliant project's repository the standard is implemented and how it fulfils the requirements. | |
| 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="Special">#</span><span class="Title"> Rejected Ideas</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">"rejected-ideas"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></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. The author should also solicit community input on a PHEP's idea before drafting the PHEP; substantial suggestions rejected during this process should also be captured. | |
| This should not be a full recap of the back-and-forth discussion, but only a summary of the significant ideas which were not selected. | |
| <span class="Special">#</span><span class="Title"> Open Issues</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">"open-issues"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></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. Suggestions may also arise from preliminary conversations before the PHEP is drafted, which should be captured if they are not resolved before writing begins. This helps make sure all issues required for the PHEP to be ready for consideration are complete. | |
| <span class="Special">#</span><span class="Title"> Footnotes</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">"footnotes"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. Other notes may be included in this section as appropriate, or it may be excluded. | |
| <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"> Copyright</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">"copyright"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="DiffChange">The text following this paragraph should be included verbatim. The BibTeX code should be updated with the PHEP number (once it is assigned) in both the citation key and the </span><span class="Special DiffChange">`</span><span class="DiffChange">number</span><span class="Special DiffChange">`</span><span class="DiffChange"> tag, the author, title, and year.</span> | |
| 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 class="Special">```</span> | |
| @techreport(phep2, | |
| author = {Jonathan T. Niehof}, | |
| title = {PHEP Template}, | |
| <span class="DiffChange"> year = {2023},</span><span class="DiffChange"> </span> | |
| type = {PHEP}, | |
| <span class="DiffChange"> number = {</span><span class="DiffText">9999</span><span class="DiffChange">},</span><span class="DiffChange"> </span> | |
| doi = {10.5281/zenodo.xxxxxxx} | |
| ) | |
| <span class="Special">```</span> | |
| </pre> | |
| </div></td> | |
| <td><div> | |
| <pre> | |
| <span class="Special">```</span> | |
| PHEP: 2 | |
| Title: PHEP Template | |
| 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/25">https://github.com/heliophysicsPy/standards/pull/25</a> | |
| <span class="DiffAdd">Revision: 1</span><span class="DiffAdd"> </span> | |
| Status: Draft | |
| Type: Informational | |
| Content-Type: text/markdown; charset=UTF-8; variant=CommonMark | |
| Requires: 1 | |
| Created: 06-Dec-2023 | |
| <span class="DiffChange">Post-History: 06-Dec-2023</span><span class="DiffText">, 28-Feb-2024</span><span class="DiffChange"> </span> | |
| <span class="Special">```</span> | |
| <span class="Special">#</span><span class="Title"> Abstract</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">"abstract"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| This PHEP provides a template to make it easier to write a PHEP-1 compliant PHEP. It does not establish or enforce any standard. Each section contains explanatory text for how to write that section in an actual PHEP. | |
| The majority of the text should be replaced with the text of your proposed PHEP. See [<span class="Underlined">Specification</span>](<span class="Constant">#specification</span>) for further directions on using this template. | |
| This section of your PHEP should include a short description of the issue being addressed. | |
| <span class="Special">#</span><span class="Title"> 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">"motivation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Discussions in the drafing of PHEP 1 indicated a desire to have a template to make it easier for potential PHEP writers to comply with the format, address the required elements, and avoid the "blank page" problem. | |
| 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. | |
| <span class="Special">#</span><span class="Title"> Rationale</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">"rationale"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| The template model should help make the initial drafting of a PHEP a fairly simple copy-paste-replace operation. Although in theory any PHEP could be taken as a template, each PHEP is unique and it is easier to have one that spans the set of expected sections, while minimizing additional information. | |
| 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="Special">#</span><span class="Title"> Specification</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">"specification"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| Use this PHEP by copying it to a new file, usually named <span class="Special">`</span>phep-9999.md<span class="Special">`</span>, and editing it. (See PHEP 1 for details on the process.) The text is in Markdown (specifically [<span class="Underlined">CommonMark</span>](<span class="Constant"><a href="https://spec.commonmark.org/">https://spec.commonmark.org/</a></span>)) and can be directly edited by any text editor. You can check the rendering of text fragments [<span class="Underlined">here</span>](<span class="Constant"><a href="https://spec.commonmark.org/dingus/">https://spec.commonmark.org/dingus/</a></span>), and editors with explicit Markdown support include: | |
| <span class="Statement">*</span> [<span class="Underlined">ReText</span>](<span class="Constant"><a href="https://github.com/retext-project/retext">https://github.com/retext-project/retext</a></span>) | |
| <span class="Statement">*</span> [<span class="Underlined">PyCharm</span>](<span class="Constant"><a href="https://www.jetbrains.com/help/pycharm/markdown.html">https://www.jetbrains.com/help/pycharm/markdown.html</a></span>) | |
| Start by updating the preamble as follows: | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">PHEP</span><span class="htmlBold">**</span> number should be 9999 until a new number is assigned by the editors. | |
| <span class="Statement DiffAdd">*</span><span class="DiffAdd"> </span><span class="htmlBold DiffAdd">**</span><span class="htmlBold DiffAdd">Title</span><span class="htmlBold DiffAdd">**</span><span class="DiffAdd"> should be the title of your PHEP. </span> | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Author</span><span class="htmlBold">**</span> should be updated with your name and (ideally) email address and ORCID. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Discussions-To</span><span class="htmlBold">**</span> is the URL of your pull request once it is opened (so this usually is not updated until the PR is open). | |
| <span class="Statement DiffAdd">*</span><span class="DiffAdd"> </span><span class="htmlBold DiffAdd">**</span><span class="htmlBold DiffAdd">Revision</span><span class="htmlBold DiffAdd">**</span><span class="DiffAdd"> is 1. </span> | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Status</span><span class="htmlBold">**</span> is Draft. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Type</span><span class="htmlBold">**</span> is "Standards Track" if proposing a requirement for PyHC packages; "Informational" for best practices and similar information; "Process" if proposing a means by which PyHC conducts itself (see PHEP 1). | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Content-Type</span><span class="htmlBold">**</span> must remain, verbatim <span class="Special">`</span>text/markdown; charset=UTF-8; variant=CommonMark<span class="Special">`</span>. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Requires</span><span class="htmlBold">**</span> should list the number of all PHEPs that this one depends on (i.e., that this one does not make sense without). Leave the header out if there are none. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Created</span><span class="htmlBold">**</span> is the date the PHEP was <span class="htmlItalic">*</span><span class="htmlItalic">assigned a number</span><span class="htmlItalic">*</span> by the editors. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Post-History</span><span class="htmlBold">**</span> should include the date of the first push to the PR (and subsequent pushes separated by commas) in <span class="Special">`</span>dd-mmm-yyyy<span class="Special">`</span>. | |
| <span class="Statement">*</span> <span class="htmlBold">**</span><span class="htmlBold">Replaces</span><span class="htmlBold">**</span> should be the number of a final PHEP which this PHEP proposes to replace, if appropriate (otherwise exclude this header). | |
| Now go through each section and fill it in with the contents of your PHEP, removing the text of this one as you go. Each section usually contains two parts. First is the relevant content for this template PHEP (if necessary). This is followed by the information that your PHEP should have within that section. | |
| The sections are not all required (in fact, strictly, none are required), but the information should be there. The author should use whatever means of organization seems appropriate, including deleting or consolidating sections, breaking sections into multiple sections, and using subsections. It is recommended to add HTML anchors after each heading to make linking easier in the future. | |
| The technical specification should completely describe the proposed standard. The specification should be detailed enough to allow competing, interoperable implementations, where applicable. | |
| <span class="Special">#</span><span class="Title"> Backwards Compatibility</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">"backwards-compatibility"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| As the PHEP process is new, this template PHEP introduces no compatibility concerns. | |
| 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. If there are none, an explicit statement that there are no backward incompatibilities is preferred to removing the section. | |
| <span class="Special">#</span><span class="Title"> Security Implications</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">"security-implications"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| This PHEP raises no security implications as it does not interact with any executing code. | |
| Any security concerns should be explicitly written out; as with backwards compatibility, an explicit statement of no implications is preferred to removing the section. | |
| <span class="Special">#</span><span class="Title"> How to Teach This</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">"how-to-teach-this"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| This PHEP is, itself, meant as a teaching aid for PHEP 1. Demonstrating the process of using the template, e.g. as part of a PyHC telecon, may be appropriate. | |
| <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="Special">#</span><span class="Title"> Reference Implementation</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">"reference-implementation"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| In a sense, this PHEP is itself a reference implementation. | |
| A reference implementation is not always necessary, but is strongly suggested for Standards Track PHEPs. In that case it would include a reference to an existing or new PyHC project which is compliant with the proposed standard and a description of how it complies. The description should point out where in the compliant project's repository the standard is implemented and how it fulfils the requirements. | |
| 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="Special">#</span><span class="Title"> Rejected Ideas</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">"rejected-ideas"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></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. The author should also solicit community input on a PHEP's idea before drafting the PHEP; substantial suggestions rejected during this process should also be captured. | |
| This should not be a full recap of the back-and-forth discussion, but only a summary of the significant ideas which were not selected. | |
| <span class="Special">#</span><span class="Title"> Open Issues</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">"open-issues"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></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. Suggestions may also arise from preliminary conversations before the PHEP is drafted, which should be captured if they are not resolved before writing begins. This helps make sure all issues required for the PHEP to be ready for consideration are complete. | |
| <span class="Special">#</span><span class="Title"> Footnotes</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">"footnotes"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| A collection of footnotes cited in the PHEP, and a place to list non-inline hyperlink targets. Other notes may be included in this section as appropriate, or it may be excluded. | |
| <span class="Special DiffAdd">#</span><span class="Title DiffAdd"> Revisions</span><span class="DiffAdd"> </span> | |
| <span class="DiffAdd">This section contains a brief summary of changes by revision number, including the date of approval.</span> | |
| <span class="DiffAdd"> </span><span class="DiffAdd"> </span> | |
| <span class="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="Identifier"><</span><span class="Statement">a</span><span class="Identifier"> </span><span class="Type">name</span><span class="Identifier">=</span><span class="Constant">"copyright"</span><span class="Identifier">></span><span class="Identifier"></</span><span class="Statement">a</span><span class="Identifier">></span> | |
| <span class="DiffChange">The text following this paragraph should be included verbatim. The BibTeX code should be updated with the PHEP number (once it is assigned) in both the citation key and the </span><span class="Special DiffChange">`</span><span class="DiffChange">number</span><span class="Special DiffChange">`</span><span class="DiffChange"> tag, the author, title, and year.</span><span class="DiffText"> Once a DOI is reserved, the BibTeX citation should be updated with the DOI for the specific revision of the PHEP.</span> | |
| 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 class="Special">```</span> | |
| @techreport(phep2, | |
| author = {Jonathan T. Niehof}, | |
| title = {PHEP Template}, | |
| <span class="DiffChange"> year = {2023</span><span class="DiffText">--2024</span><span class="DiffChange">},</span><span class="DiffChange"> </span> | |
| type = {PHEP}, | |
| <span class="DiffChange"> number = {</span><span class="DiffText">2</span><span class="DiffChange">},</span><span class="DiffChange"> </span> | |
| doi = {10.5281/zenodo.xxxxxxx} | |
| ) | |
| <span class="Special">```</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