PHEP 2: PHEP template #25
Conversation
|
@sapols , hoping I can ask you to serve as editor again :) In particular I didn't want to just "steal" number 2...gotta do these things right. My thought is to edit and force push once the number is assigned. I think this makes the history more clear, and I can update PHEP 1 to explicitly say force-push is okay while the PR is in draft (not the same as the PHEP being in draft!)--it makes it easier to track the filename. |
jtniehof
force-pushed
the
phep-template
branch
from
0e16bd2 to
9f41783
Compare
|
Phenomenal template. Love it. |
Good for me to self-assign PHEP 2 and non-draft, or do you need further format/compliance review? |
I could use a bit longer to re-read it one last time, closer. |
jtniehof
force-pushed
the
phep-template
branch
from
9f41783 to
1bba0a8
Compare
Done, and thanks! |
|
Didn't mean to add myself as an official reviewer on this. @sapols 's got the ultimate approval as editor on this PHEP, but I'm throwing support behind the comment he made :
|
Anybody can do a GH "review" of the PR to give their feedback, so no problem. The editorial decision is just at assigning a number and going from draft to "ready for review". |
|
New version pushed largely reflecting the revision process in PHEP 1 (#22) |
|
@jtniehof I found it great to use, no notes! I second moving to vote as-is. |
|
Looks good to me. Suggest clarifying that the DOI should be for the PHEP document, not the repository, and when the DOI should be updated (assuming version control on the DOI). |
pheps/phep-0002.md
Outdated
|
|
||
| # Copyright | ||
| <a name="copyright"></a> | ||
| 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 `number` tag, the author, title, and year. Once a DOI is reserved, the BibTeX citation should be updated with the DOI for the specific revision of the PHEP. |
There was a problem hiding this comment.
| 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 `number` tag, the author, title, and year. Once a DOI is reserved, the BibTeX citation should be updated with the DOI for the specific revision of the PHEP. | |
| 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 `number` tag, the author, title, and year. Once a DOI is reserved for the document (not the repository), the BibTeX citation should be updated with the DOI for the specific revision of the PHEP. |
There was a problem hiding this comment.
Was the vote to approve assuming the inclusion of this change?
There was a problem hiding this comment.
Excellent. Just pushed a minor revision with this change and the link to the first vote.
| 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. | ||
|
|
There was a problem hiding this comment.
| # Use cases | |
| <a name="use-cases"></a> | |
I'm wondering — would it make sense to have a section in the template for use cases?
There was a problem hiding this comment.
That might go in "how to teach this" although I also understand how it would make sense in rationale.
The structure of PHEP2 directly follows the sections from PHEP1. So structural changes should probably go in #27. Further guidance/suggestion/nudges could go in here. I'm a little nervous about having substantive guidance hiding within a template though--in theory PHEP2 is merely a convenience not some sort of definitive, or even best-practices, reference.
|
This PHEP unanimously passed its second round of voting at the 2024 Fall Meeting. People who voted:
And a note on process: For future second-round votes on PHEPs, we decided at the Fall Meeting to use GitHub's PR "approve" to record votes. |
|
TODO: get a DOI for this doc, post resolution, merge PR. |
|
Thanks @sapols . I will get things together and Zenodo'd over the next couple of days. |
|
@sapols, this is now ready to merge and mark as release. Once that is done, I will put the final hash on Zenodo and publish there. See Creating Files and Release, second bullet. Tag phep-2-1 (for consistency with PHEP 1). Attached is the final PHEP to use as the release file: phep-0002.pdf Thanks! |
|
Yep, I linked that because it's basically the only notes document we've had. In general we haven't had notes go up particularly quickly after these meetings--that's not a complaint, there's a lot going on in PyHC. I've just been linking to where the notes are going to go as best as I can, but we can take whatever approach makes sense. Since we do have the list in the PR, I figure that's an okay backstop (although I think @Cadair abstained based on the Slack?) |
|
Spoke to Julie offline. Sounds like we're gonna wait for the full meeting report which will contain a tally of who voted. So we'll hold off on merging this until we can put that report as the second resolution link. |
|
np, let me know when it's ready. Then I can either do another post-history entry or amend and force-push, as appropriate...for something like this I don't think rewriting history is bad. |
This is a template following the format requirements of PHEP 1 (#22) with the intention of making it easier to copy/paste into starting a new PHEP.
The template does mix directions on what to do, the PHEP-required content of PHEP 2 itself, and the content to be filled in on the new PHEP. I hope that's not too unclear--we could try, say, italicizing everything to make it clear if someone using the template leaves in template language, but that doesn't solve the problem of distinguishing the rest. Maybe it's perfectly clear to the reader.