Require meaningful PR titles

There seem to be a lot of PRs that get opened with the title “Update {file}”. Would it make sense to have a bot auto-reply with something like this?

Hi @{username},

Thanks for your contribution. I noticed your PR has the title “{title}”, which makes it hard to guess what its purpose is just from reading the title. Please change its title to something more specific (but still short).

Examples of bad PR titles:
* Update spam.py
* Change eggs.rst
* Fix spam.eggs_function

Better PR titles:
* Typo: pyhton —> python
* gh-0000: Reorganize spam module docs
* gh-0000: Clarify spam.eggs_function docs
* gh-0000: Increase test coverage of spam.eggs_function

Thanks!
5 Likes

These are probably the ones created by editing a file from the GitHub UI, since by default it suggests Update <filename> for the commit message, and then for the PR title.

It might be better to write a short paragraph explaining the problem, and link to a page of the devguide that has a longer explanation, including the fact that PRs should have an issue and NEWS entry unless they trivial.

The same could be done for PRs with an empty body, and maybe ignore PRs made by core devs.

1 Like

Maybe we can create several kinds of PR templates, and each template can provide suggestions of the PR title.

I.e template for bugfix, new implementation, typo fix, test improvement etc?

2 Likes

I’m not a core dev, but this has worked well for other projects I maintain, so long as the templates are kept short, relevant and to the point (as otherwise people tend to not read them). I’m not sure if you can make PR templates act like the newer GH issue forms and actually validate the inputs given, apply tags, etc., but if so that might be an even better solution.

1 Like

As far as I understand, you can either define a single PR template that will automatically be included in the body of every PR or you can define multiple templates, but it seems that the only way to pick one is to manually add &template=some-template.md to the PR URL.

Ah, I see. I suppose you could have links to the templates in the devguide (or elsewhere that GitHub exposes, e.g. Readme, Contributing Guide, etc), but while that might be of some utility for users actually following those resources, I’d be willing to bet that the great majority of new contributors (as I figure they pretty much all are) are drive-bys who aren’t actually carefully reading such, or they’d surely take a few seconds to write an actually useful title.

And for that matter, the requirements for the PR table are right at the top of the current PR template, visible “above the fold”, and yet those folks presumably aren’t reading them already, so I’m not sure how much different PR templates are going to help. Its the same for us on the PEPs repo; the one thing our PR template says is how to format the PR title, and yet many users (of all different skill levels) don’t read and follow it either, heh.

On the other hand, since anyone with write permissions can edit a PR title, its a pretty simple problem to fix compared to issues with the code, and something I’m routinely used to doing on the PEPs repo.

Note, for single-commit PRs, it’s the commit message that is used, not the PR title.

FTR, here’s how GitHub deals with squash-and-merge (more or less copied from GitHub, so you don’t have to chase links):

PR type Summary[1] Description[2]
Single-commit PR The title of the commit message for the single commit, followed by the pull request number The body text of the commit message for the single commit
Multi-commit PR The pull request title, followed by the pull request number A list of the commit messages for all of the squashed commits, in date order

  1. Merge commit title ↩︎

  2. Merge commit body ↩︎

1 Like

Ah, so that’s what happened to you on python/peps#2586 and why my title update didn’t stick. I now recall running into that before, but I find that behavior rather inexplicable, since the title itself is generated directly from the commit message for such PRs, so it doesn’t make much sense why it would ignore any updates to such and behave inconsistently to multi-commit PRs. Especially on mobile, where the only way to edit it is for the author to push a new commit or amend the existing one…but it is what it is, I guess.

You can still edit the commit message before merging, you just need to remember if you need to do it before or after clicking the squash-and-merge button, depending on which UI you are on :wink:

1 Like

Instead of “Better PR titles”, I’m inclined to reword it stricter. Maybe “Required PR title format” is too strict.