specs icon indicating copy to clipboard operation
specs copied to clipboard

add PR template for new SPECs

Open drammock opened this issue 8 months ago • 1 comments

@jarrodmillman proposed this idea at the Summit and I volunteered to implement. However, I'm actually not sure it's a good idea to merge this, because:

  1. The template's current location and filename should mean that it shows up on every new PR; however, this repo gets PRs other than new SPEC proposals (e.g., to update draft SPECs, add project endorsements, etc), and the PR template won't be relevant for those.
  2. Although GH allows a repo to have multiple PR templates, they aren't selectable through the UI like issue templates are; they require manually adding URL query parameters like ?template=propose_a_new_spec.md. (They also require storing the templates in .github/PULL_REQUEST_TEMPLATE/, and if one does so, new PRs opened through the UI will not use any template at all.)

It might be possible to hack a solution by making a default template at .github/pull_request_template.md that includes relative links to the various templates using URL query parameters (example here), but that feels a bit brittle / over-engineered. LMK if there's appetite for that approach though, and I can give it a shot.

Other note: while Issue templates can be defined in YAML files and include built-in validation, PR templates cannot. Validation would have to use a GH Action (example here).

drammock avatar May 22 '25 21:05 drammock

Ohh, it's too bad that unlike issues, we cannot template different types of PRs.

Maybe then just a link to a docs page and template? Or a bot comment with the checklist on any PRs that adds a new spec file/directory? (Though that will be just as after the fact as us commenting)

bsipocz avatar May 22 '25 22:05 bsipocz

OK, so I tried "the fancy way" and it seems to work:

Screenshot 2025-06-09 at 14-53-48 Comparing main bar · drammock_specs

To get the proof-of-concept I had to merge this PR's changes into main of my fork (PR templates are only used for pulls against a repo's default branch), and then make a PR into my fork's main branch. Clicking the "preview" tab does make the link active, and clicking the link does populate the description with the template text (and does preserve the base and compare branches). I have every reason to assume it will work for cross-fork pulls too, once these changes were merged in here. So I think now it's up to the community / @scientific-python/spec-steering-committee as to whether this is a net positive change, or too baroque to be worthwhile.

EDIT: here's the URL if you want to fiddle with the UX: https://github.com/drammock/specs/compare/main...drammock:specs:bar?expand=1

drammock avatar Jun 09 '25 19:06 drammock

FWIW having a template is nice. Thanks!

pllim avatar Jun 10 '25 01:06 pllim

I would think this can be flipped out from being a draft?

bsipocz avatar Jul 21 '25 23:07 bsipocz

Thanks @drammock!

stefanv avatar Jul 25 '25 01:07 stefanv