Clarify contribution guidelines to include better descriptions for PR titles #19211
Conversation
In addition to an issue number, the title of a PR should contain a brief description; then users can follow the progress more easily from the title.
|
And it should ideally include a few words as to why the fix actually fixes the problem. |
Ref #17547 (comment)
Ref #17718 (comment) |
|
I have no intention to follow this guideline so I cannot accept it. The problem is real, but the solution is to write some simple tool that makes "git log" more useful. |
|
Wouldn't it be easier for you to write a tool to compose commit messages that any git user can, uh, use? |
Ok. Then I would like this PR to be open for a while, so people can still discuss a better solution.
Well it is also |
|
How about I change |
How is Yes, a custom tool could scrape the information from the related Github issue, but imo we shouldn't rely on Github for this kind of information in the first place. |
|
Definitely in favour of this guideline. Certainly tooling would be a more reliable way to solve this though. I think there are many options we could consider:
So yeah, I do sympathise with Araq's stance. Automating away this manual work as much as possible is worthwhile. But at the same time I think we can also just merge this and hope it has some impact on contributors. Btw the title of this PR should reflect it better too IMO, I was really confused when I first read it :). Something like "Clarify contribution guidelines to include better descriptions" would be better. |
Make sense. |
ringabout
changed the title
IMHO, ideally we can use a PR template to suggest newcomers what to do: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository |
If you don't automate it, it'll be unreliable, so not "relying on Github" is a very bad idea. |
|
Generally a tool can't solve this problem - the whole idea with a commit message is that it describes the change, such that when the next developer looks at it, the rationale for making the change in a particular are clear - a bug report rarely includes information like this - a commit line "code snipped xyz crashes the compiler" is not much more helpful than "fixes ". A commit message is a communications tool where you're telling a story to future developers and users - they don't have the luxury of asking questions, so you have to anticipate what their questions will be - often, these questions are along the lines of "why was this design chosen" or "what flow was intended in this fix". An example is "xyz crashes compiler" (the bug report) and "generic types must be made concrete before operation X is performed" (the commit) - the latter tells the next developer how to fit the next bugfix or feature into the flow. |
|
@narimiran pointed out that it would simplify his backporting efforts too, so I'll try to follow this new guideline. |
In addition to an issue number, the title of a PR should contain a brief description; then users can follow the progress more easily from the title.
In addition to an issue number, the title of a PR should contain a brief description; then users can follow the progress more easily from the title.
Thank @haxscramper
The commit messages are not very clear and it is hard to know the progress of Nim language at the moment at first sight.