Hi,
This is a friendly reminder to everyone about the preferred way to link to bugs in your commit messages. When you include them as part of the footer, they are indexed and are thus searchable. For example:
""" Fixing some weird bug
More explanation Blah blah blah.
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
-Chad
I actually prefer bug numbers in the header.
When looking at the gerrit dashboard it's useful to see from the commit message whether it is a bug or enhancement to determine what code I should review first (bugs always win).
I also tend to write very verbose commit messages so I like to put the bug in the header so the message itself can be ignored if necessary.
Apologies in advanced if I have started another bike shed conversation.. :D
On Fri, Mar 1, 2013 at 1:46 PM, Chad innocentkiller@gmail.com wrote:
Hi,
This is a friendly reminder to everyone about the preferred way to link to bugs in your commit messages. When you include them as part of the footer, they are indexed and are thus searchable. For example:
""" Fixing some weird bug
More explanation Blah blah blah.
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
-Chad
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Fri, Mar 1, 2013 at 2:20 PM, Jon Robson jdlrobson@gmail.com wrote:
I actually prefer bug numbers in the header.
+1, also useful for release notes. Could the footer line be auto-generated for indexing purposes?
Yay for bikeshed topics ;-)
Commit messages could also be used for altering release-notes file as proposed in release-notes-bot RFChttp://www.mediawiki.org/wiki/Requests_for_comment/RELEASE-NOTES_bot to avoid constant merge conflicts.
On Fri, Mar 1, 2013 at 5:23 PM, Erik Moeller erik@wikimedia.org wrote:
On Fri, Mar 1, 2013 at 2:20 PM, Jon Robson jdlrobson@gmail.com wrote:
I actually prefer bug numbers in the header.
+1, also useful for release notes. Could the footer line be auto-generated for indexing purposes?
Yay for bikeshed topics ;-)
Erik Möller VP of Engineering and Product Development, Wikimedia Foundation
Support Free Knowledge: https://wikimediafoundation.org/wiki/Donate
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Well, that's true if you're only building release notes by copy+pasting the first line. If it's scripted, it's trivial to pull the bug # from the footer as well.
And no, commit messages cannot be auto-generated by Gerrit, as that changes the sha1.
-Chad
On Fri, Mar 1, 2013 at 2:23 PM, Erik Moeller erik@wikimedia.org wrote:
On Fri, Mar 1, 2013 at 2:20 PM, Jon Robson jdlrobson@gmail.com wrote:
I actually prefer bug numbers in the header.
+1, also useful for release notes. Could the footer line be auto-generated for indexing purposes?
Yay for bikeshed topics ;-)
Erik Möller VP of Engineering and Product Development, Wikimedia Foundation
Support Free Knowledge: https://wikimediafoundation.org/wiki/Donate
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
The proposalhttp://www.mediawiki.org/wiki/Requests_for_comment/RELEASE-NOTES_botis for a bot to parse commit message for special "commands" to add some text to specific sections of the release-notes file. When bot detects a master merge, it will pull the latest release-notes, change it, and merge it to master right away, avoiding any conflicts.
If the bot messes up, or if a more complex file edit is needed, we can do it through the regular git/gerrit process.
On Fri, Mar 1, 2013 at 5:28 PM, Chad innocentkiller@gmail.com wrote:
Well, that's true if you're only building release notes by copy+pasting the first line. If it's scripted, it's trivial to pull the bug # from the footer as well.
And no, commit messages cannot be auto-generated by Gerrit, as that changes the sha1.
-Chad
On Fri, Mar 1, 2013 at 2:23 PM, Erik Moeller erik@wikimedia.org wrote:
On Fri, Mar 1, 2013 at 2:20 PM, Jon Robson jdlrobson@gmail.com wrote:
I actually prefer bug numbers in the header.
+1, also useful for release notes. Could the footer line be auto-generated for indexing purposes?
Yay for bikeshed topics ;-)
Erik Möller VP of Engineering and Product Development, Wikimedia Foundation
Support Free Knowledge: https://wikimediafoundation.org/wiki/Donate
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Le 01/03/13 14:37, Yuri Astrakhan wrote:
The proposalhttp://www.mediawiki.org/wiki/Requests_for_comment/RELEASE-NOTES_botis for a bot to parse commit message for special "commands" to add some text to specific sections of the release-notes file. When bot detects a master merge, it will pull the latest release-notes, change it, and merge it to master right away, avoiding any conflicts.
If the bot messes up, or if a more complex file edit is needed, we can do it through the regular git/gerrit process.
So instead of us just writing to the RELEASE-NOTES we will instead have to pass commands to yet another unstable bot that will do it for us?
What is the added values beside adding overhead to the process?
On Sat, Mar 2, 2013 at 9:08 AM, Antoine Musso hashar+wmf@free.fr wrote:
Le 01/03/13 14:37, Yuri Astrakhan wrote:
The proposalhttp://www.mediawiki.org/wiki/Requests_for_comment/RELEASE-NOTES_botis for a bot to parse commit message for special "commands" to add some text to specific sections of the release-notes file. When bot detects a master merge, it will pull the latest release-notes, change it, and merge it to master right away, avoiding any conflicts.
If the bot messes up, or if a more complex file edit is needed, we can do it through the regular git/gerrit process.
So instead of us just writing to the RELEASE-NOTES we will instead have to pass commands to yet another unstable bot that will do it for us?
What is the added values beside adding overhead to the process?
I don't like the idea of a bot doing this. Nor do I think writing release notes at commit time works well either (too many stupid conflicts).
Most other groups using Gerrit that I know of tend to write their release notes right before releases. Sometime shortly before a release, they'll go through a full change of putting the release notes together. Then if any other things are done before the release, you just submit another commit to it.
See: https://gerrit-review.googlesource.com/#/c/39210/ and then https://gerrit-review.googlesource.com/#/c/42790/ and https://gerrit-review.googlesource.com/#/c/42671/
I don't see a huge problem in going this direction ourselves.
-Chad
I don't like the idea of a bot doing this. Nor do I think writing release notes at commit time works well either (too many stupid conflicts).
What's the issue with a bot appending a few lines to a release-notes section if it sees it the commit message? But yes, release-notes conflicts are a major pain and kills the streamlined patching workflow - submit->review->merge, frequently requiring extra "->fix->review" steps right before merge.
Most other groups using Gerrit that I know of tend to write their release notes right before releases. Sometime shortly before a release, they'll go through a full change of putting the release notes together. Then if any other things are done before the release, you just submit another commit to it.
Might not work well with so many committers and no strict central project management. It will become a big burden to go through all commits and pull out all relevant release-notes (actually doing what the bot will be doing, only in a non-automated fashion because the commit messages won't be as structured). But if someone is willing to do that... sure, why not :)
Yuri Astrakhan yuriastrakhan@gmail.com wrote:
I don't like the idea of a bot doing this. Nor do I think writing release notes at commit time works well either (too many stupid conflicts).
What's the issue with a bot appending a few lines to a release-notes section if it sees it the commit message? But yes, release-notes conflicts are a major pain and kills the streamlined patching workflow - submit->review->merge, frequently requiring extra "->fix->review" steps right before merge.
[...]
As I wrote at http://www.mediawiki.org/wiki/Talk:Git/Workflow#Release_notes_conflicts_2076..., this can be easily re-streamlined with a merge driver. As release notes for MediaWiki are probably mostly additions, it shouldn't be too hard to cover the common cases, and we certainly don't have the ambition to do text analysis in C, but can settle for Perl (or Python or even PHP :-)) instead.
Tim
As I wrote at
http://www.mediawiki.org/wiki/Talk:Git/Workflow#Release_notes_conflicts_2076... , this can be easily re-streamlined with a merge driver. As release notes for MediaWiki are probably mostly additions, it shouldn't be too hard to cover the common cases, and we certainly don't have the ambition to do text analysis in C, but can settle for Perl (or Python or even PHP :-)) instead.
Tim, it would be great if this worked on the gerrit side, but apparently
it has to be implemented in java in order to work with the gerrit server (at least that's what i was told). Implementing a core gerrit feature like that might be a bit more resource intensive than having a simple bot... (?)
Yuri Astrakhan yuriastrakhan@gmail.com wrote:
As I wrote at
http://www.mediawiki.org/wiki/Talk:Git/Workflow#Release_notes_conflicts_2076... , this can be easily re-streamlined with a merge driver. As release notes for MediaWiki are probably mostly additions, it shouldn't be too hard to cover the common cases, and we certainly don't have the ambition to do text analysis in C, but can settle for Perl (or Python or even PHP :-)) instead.
Tim, it would be great if this worked on the gerrit side, but apparently
it has to be implemented in java in order to work with the gerrit server (at least that's what i was told). Implementing a core gerrit feature like that might be a bit more resource intensive than having a simple bot... (?)
Apparently, this is really not possible. Gerrit seems to use JGit for the basic stuff, and merge drivers aren't part of that. NIH sucks.
Bartosz Dziewoński matma.rex@gmail.com wrote:
As I wrote at http://www.mediawiki.org/wiki/Talk:Git/Workflow#Release_notes_conflicts_2076..., this can be easily re-streamlined with a merge driver. As release notes for MediaWiki are probably mostly additions, it shouldn't be too hard to cover the common cases, and we certainly don't have the ambition to do text analysis in C, but can settle for Perl (or Python or even PHP :-)) instead.
I wrote a very simple one some time ago, in Ruby. https://github.com/MatmaRex/mediawikireleasenotes-driver
It doesn't really work. There are enough changes that are not simple additions that it solves no more than about 30% conflics for me. Maybe that rate could be improved using, like, a real algorithm for merging; but the naive solution doesn't really work.
Ah, actual, running code! :-) 30 % isn't that bad for about ten (!) lines. And it helps developers as it means rebases might still be necessary, but can be automated in 30 % of the times without manual intervention.
Let's add your driver to http://www.mediawiki.org/wiki/Git/Workflow#Build_failed_due_to_merge_conflic.... I think it's probably preferable to have a separate file for the driver itself and manual installation instructions as otherwise people will just complain "mediawikireleasenotes-driver-installer.sh didn't work for my setup!!11!", but that's no blocker.
Tim
On Mon, 04 Mar 2013 17:03:58 +0100, Tim Landscheidt tim@tim-landscheidt.de wrote:
Bartosz Dziewoński matma.rex@gmail.com wrote:
I wrote a very simple one some time ago, in Ruby. https://github.com/MatmaRex/mediawikireleasenotes-driver
It doesn't really work. There are enough changes that are not simple additions that it solves no more than about 30% conflics for me. Maybe that rate could be improved using, like, a real algorithm for merging; but the naive solution doesn't really work.
[...]
Let's add your driver to http://www.mediawiki.org/wiki/Git/Workflow#Build_failed_due_to_merge_conflic....
Please go ahead if you think it's worth it. I didn't because in general I deemed the result not good enough, and when the automatic merge fails, you lose the information about branches being merged (try it).
I think it's probably preferable to have a separate file for the driver itself and manual installation instructions as otherwise people will just complain "mediawikireleasenotes-driver-installer.sh didn't work for my setup!!11!", but that's no blocker.
I can't imagine a setup where it wouldn't just work (other than you not running the installer inside a .git directory). And sharing the file + instructions insted of the installer is a big can of worms. (Where do you store the .rb driver file? Where do you add the entry for merging RELEASE-NOTES? Which config do you edit? How? git has a lot of options for all these things...)
All these issues with the git-side driver is the reason I think we should have a master-branch-monitoring bot that will update RELEASE-NOTES based on commit messages. Easy to track changes, easy to fix problems. Might be a bit more work than a driver though.
On Tue, Mar 5, 2013 at 12:30 PM, Bartosz Dziewoński matma.rex@gmail.comwrote:
On Mon, 04 Mar 2013 17:03:58 +0100, Tim Landscheidt < tim@tim-landscheidt.de> wrote:
Bartosz Dziewoński matma.rex@gmail.com wrote:
I wrote a very simple one some time ago, in Ruby.
https://github.com/MatmaRex/**mediawikireleasenotes-driverhttps://github.com/MatmaRex/mediawikireleasenotes-driver
It doesn't really work. There are enough changes that are not simple
additions that it solves no more than about 30% conflics for me. Maybe that rate could be improved using, like, a real algorithm for merging; but the naive solution doesn't really work.
[...]
Let's add your driver to http://www.mediawiki.org/wiki/**Git/Workflow#Build_failed_due_** to_merge_conflicthttp://www.mediawiki.org/wiki/Git/Workflow#Build_failed_due_to_merge_conflict .
Please go ahead if you think it's worth it. I didn't because in general I deemed the result not good enough, and when the automatic merge fails, you lose the information about branches being merged (try it).
I think it's probably preferable to have a separate file for
the driver itself and manual installation instructions as otherwise people will just complain "mediawikireleasenotes-driver-**installer.sh didn't work for my setup!!11!", but that's no blocker.
I can't imagine a setup where it wouldn't just work (other than you not running the installer inside a .git directory). And sharing the file + instructions insted of the installer is a big can of worms. (Where do you store the .rb driver file? Where do you add the entry for merging RELEASE-NOTES? Which config do you edit? How? git has a lot of options for all these things...)
-- Matma Rex
______________________________**_________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/**mailman/listinfo/wikitech-lhttps://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Sat, 02 Mar 2013 21:17:29 +0100, Tim Landscheidt tim@tim-landscheidt.de wrote:
As I wrote at http://www.mediawiki.org/wiki/Talk:Git/Workflow#Release_notes_conflicts_2076..., this can be easily re-streamlined with a merge driver. As release notes for MediaWiki are probably mostly additions, it shouldn't be too hard to cover the common cases, and we certainly don't have the ambition to do text analysis in C, but can settle for Perl (or Python or even PHP :-)) instead.
I wrote a very simple one some time ago, in Ruby. https://github.com/MatmaRex/mediawikireleasenotes-driver
It doesn't really work. There are enough changes that are not simple additions that it solves no more than about 30% conflics for me. Maybe that rate could be improved using, like, a real algorithm for merging; but the naive solution doesn't really work.
On Sat, 02 Mar 2013 18:35:06 +0100, Chad innocentkiller@gmail.com wrote:
Most other groups using Gerrit that I know of tend to write their release notes right before releases. Sometime shortly before a release, they'll go through a full change of putting the release notes together. Then if any other things are done before the release, you just submit another commit to it.
I don't see a huge problem in going this direction ourselves.
So you're volunteering to write release notes for my commits? By all means, if so.
But I'm afraid this would end with simply no release notes being written.
Who would want to read and deeply understand 2000 commit messages per release to note all the bugs being fixed and all the implications they might have for end-users? I certainly wouldn't (and wouldn't even want to do this for my own commits some three months after I made them).
On 02/03/13 19:13, Bartosz Dziewoński wrote:
So you're volunteering to write release notes for my commits? By all means, if so.
But I'm afraid this would end with simply no release notes being written.
Who would want to read and deeply understand 2000 commit messages per release to note all the bugs being fixed and all the implications they might have for end-users? I certainly wouldn't (and wouldn't even want to do this for my own commits some three months after I made them).
You would at least need some release-notes marker added by the commiter so that you can skip non-RL-worthy ones.
You would at least need some release-notes marker added by the commiter so that you can skip non-RL-worthy ones.
That marker is exactly what I am proposing - if we formalizehttp://www.mediawiki.org/wiki/Requests_for_comment/RELEASE-NOTES_botthe commit messages, the release notes write themselves :)
On Sat, Mar 2, 2013 at 3:16 AM, Chad innocentkiller@gmail.com wrote:
Hi,
This is a friendly reminder to everyone about the preferred way to link to bugs in your commit messages. When you include them as part of the footer, they are indexed and are thus searchable. For example:
""" Fixing some weird bug
More explanation Blah blah blah.
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
I also prefer it in the header. The bug report is the best description :)
Is it not possible for Gerrit to search if its in the header? or make it so
-Chad
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Fri, 01 Mar 2013 14:45:14 -0800, Nischay Nahata nischayn22@gmail.com wrote:
On Sat, Mar 2, 2013 at 3:16 AM, Chad innocentkiller@gmail.com wrote:
Hi,
This is a friendly reminder to everyone about the preferred way to link to bugs in your commit messages. When you include them as part of the footer, they are indexed and are thus searchable. For example:
""" Fixing some weird bug
More explanation Blah blah blah.
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
I also prefer it in the header. The bug report is the best description :)
Is it not possible for Gerrit to search if its in the header? or make it so
+1
Tools should be coded around people. Not the other way around.
On Fri, Mar 1, 2013 at 2:59 PM, Daniel Friesen daniel@nadir-seen-fire.com wrote:
On Fri, 01 Mar 2013 14:45:14 -0800, Nischay Nahata nischayn22@gmail.com wrote:
On Sat, Mar 2, 2013 at 3:16 AM, Chad innocentkiller@gmail.com wrote:
Hi,
This is a friendly reminder to everyone about the preferred way to link to bugs in your commit messages. When you include them as part of the footer, they are indexed and are thus searchable. For example:
""" Fixing some weird bug
More explanation Blah blah blah.
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
I also prefer it in the header. The bug report is the best description :)
Is it not possible for Gerrit to search if its in the header? or make it so
+1
Tools should be coded around people. Not the other way around.
No, Gerrit cannot detect these in the header. Also, this is pretty standard Git-fu to include this sort of metadata in the footer of the commit.
-Chad
"Daniel Friesen" daniel@nadir-seen-fire.com wrote:
This is a friendly reminder to everyone about the preferred way to link to bugs in your commit messages. When you include them as part of the footer, they are indexed and are thus searchable. For example:
""" Fixing some weird bug
More explanation Blah blah blah.
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
I also prefer it in the header. The bug report is the best description :)
Is it not possible for Gerrit to search if its in the header? or make it so
+1
Tools should be coded around people. Not the other way around.
*Argl* :-) May I repeat my question from http://article.gmane.org/gmane.science.linguistics.wikipedia.technical/66432:
| Is there another software project that uses the summary line | in a similar way to MediaWiki?
Tim
fwiw this is not a discussion about Gerrit features but about git commit and code contribution good practices in general. There is plenty of literature out there.
I also prefer it in the header. The bug report is the best description :)
A bug report is supposed to describe a problem while the title of a commit message is supposed to describe the solution implemented.
Plus you are limited to 50 chars. The bug number will take 5, that leaves you less than 45.
Plus quite frequently a bug is fixed through more than one commit, and still you are supposed to explain in each commit message what you are doing in that commit.
Is it not possible for Gerrit to search if its in the header?
Is this helpful?
status:merged message:<yourString>
http://stackoverflow.com/questions/14409413/searching-gerrit-by-commit-messa...
Tools should be coded around people. Not the other way around.
Agree. A 100% human readable commit message title describing what a commit does feels more human than "Fixes Bug 12345" + <truncated bug description>
Is there another software project that uses the summary line in a similar way to MediaWiki?
That was the best question of this thread. I have done some research, and the guidelines I found mentioning the inclusion of bug numbers in commit messages pointed all to a specific bug line after the commit description and an empty line - which is in line with our guidelines. Gerrit and other Git tools understand that line as metadata and you can do good things with it (as we are on our way of doing between Gerrit and Bugzilla):
OpenStack Git Commit Good Practice https://wiki.openstack.org/wiki/GitCommitMessages
Chromium - Contributing code http://www.chromium.org/developers/contributing-code
Qt - Introduction to Gerrit http://qt-project.org/wiki/Gerrit-Introduction
GNOME - a guide to writing git commit messages http://blogs.gnome.org/danni/2011/10/25/a-guide-to-writing-git-commit-messag...
EGit - Contributor Guide http://wiki.eclipse.org/EGit/Contributor_Guide
Gerrit Code Review - Contributing https://gerrit-review.googlesource.com/Documentation/dev-contributing.html
Proper Git Commit Messages and an Elegant Git History http://ablogaboutcode.com/2011/03/23/proper-git-commit-messages-and-an-elega...
On 2013-03-03 9:36 PM, "Quim Gil" qgil@wikimedia.org wrote:
[...]
Plus quite frequently a bug is fixed through more than one commit, and
still you are supposed to explain in each commit message what you are doing in that commit
I don't see that as being an issue. If anything its an argument for putting bug number in header. You can't say (part 1/2 bug XXXX) in a footer line.
[...]
Is there another software project that uses the summary line in a similar way to MediaWiki?
That was the best question of this thread. I have done some research, and
the guidelines I found mentioning the inclusion of bug numbers in commit messages pointed all to a specific bug line after the commit description and an empty line - which is in line with our guidelines. Gerrit and other Git tools understand that line as metadata and you can do good things with it (as we are on our way of doing between Gerrit and Bugzilla):
[...]
If all the other open source projects jumped off a bridge... ;-)
Personally I prefer it in the first line. Second to a good one line summary of what was done, the bug number is the next most important thing. It allows one to see the context the commit was made in. Having it in the first line allows one to find it easily and have it displayed in various "one line" log formats ( including in gerrit when you get a list of commits)
The primary argument for changing the format is so gerrit can index it. Beyond the /sounds like a gerrit problem/ argument presented previously, I would additionally argue that that is not that useful a feature. (Even if on the surface it sounds cool). Any commit fixing a bug should be listed on the bug. If I have the bug number I can just look at the bug to find the relavent commits.
That said, at the end of the day I don't think it really matters much either way.
--bawolff
_______________________________________________
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Sun, Mar 3, 2013 at 9:06 PM, Brian Wolff bawolff@gmail.com wrote:
The primary argument for changing the format is so gerrit can index it. Beyond the /sounds like a gerrit problem/ argument presented previously, I would additionally argue that that is not that useful a feature. (Even if on the surface it sounds cool). Any commit fixing a bug should be listed on the bug. If I have the bug number I can just look at the bug to find the relavent commits.
For the moment, I'm just going to do both "(bug ###)" in the header and "Bug: ###" as a footer. When I remember, anyway.
FWIW, I also prefer to have those 10 extra characters in the header. Also, when I'm scanning the git shortlog, I don't give a damn about bug numbers, because if I care enough about a commit to want to check its bug report, it's very likely I'm already looking at the full commit message anyway.
But that's just my opinion.
*--* *Tyler Romeo* Stevens Institute of Technology, Class of 2015 Major in Computer Science www.whizkidztech.com | tylerromeo@gmail.com
On Sun, Mar 3, 2013 at 6:06 PM, Brian Wolff bawolff@gmail.com wrote:
Personally I prefer it in the first line. Second to a good one line summary of what was done, the bug number is the next most important thing. It allows one to see the context the commit was made in. Having it in the first line allows one to find it easily and have it displayed in various "one line" log formats ( including in gerrit when you get a list of commits)
Yeah, that's my perspective as a user of this info as well. Having the bug numbers visible in Gerrit's list views is pretty handy for me (while I doubt I'd personally use the Bug:# search much, which is not to say it's not useful).
That said, most of the time, the bug's also in the topic, so it's not a huge deal, and I promise this will be my last response in this thread. :P Although .. perhaps in some magical future the bug # could be displayed and clickable in a separate list view column if the Bug: field is set? ;-)
Erik
On Mon, Mar 4, 2013 at 7:06 AM, Quim Gil qgil@wikimedia.org wrote:
fwiw this is not a discussion about Gerrit features but about git commit and code contribution good practices in general. There is plenty of literature out there.
I also prefer it in the header. The bug report is the best description :)
A bug report is supposed to describe a problem while the title of a commit message is supposed to describe the solution implemented.
Plus you are limited to 50 chars. The bug number will take 5, that leaves you less than 45.
Plus quite frequently a bug is fixed through more than one commit, and still you are supposed to explain in each commit message what you are doing in that commit.
I like to know about the problem before the solution implemented, that saves me some time to think what solutions could be possible. But that doesn't mean it always have to be in the header. It matters from the point of view, looking like a bug fixer you are more concerned with bug numbers while other people are concerned about what is implemented.
But what I find more important is see the bug numbers in the Gerrit 'view', its easy to find the change for a particular bug being solved. Having a separate column (as Erik suggested) for that would be the best solution :)
Is it not possible for Gerrit to search if its in the header?
Is this helpful?
status:merged message:<yourString>
http://stackoverflow.com/**questions/14409413/searching-** gerrit-by-commit-messagehttp://stackoverflow.com/questions/14409413/searching-gerrit-by-commit-message
Tools should be coded around people. Not the other way around.
Agree. A 100% human readable commit message title describing what a commit does feels more human than "Fixes Bug 12345" + <truncated bug description>
Is there another software project that uses the summary line
in a similar way to MediaWiki?
That was the best question of this thread. I have done some research, and the guidelines I found mentioning the inclusion of bug numbers in commit messages pointed all to a specific bug line after the commit description and an empty line - which is in line with our guidelines. Gerrit and other Git tools understand that line as metadata and you can do good things with it (as we are on our way of doing between Gerrit and Bugzilla):
OpenStack Git Commit Good Practice https://wiki.openstack.org/**wiki/GitCommitMessageshttps://wiki.openstack.org/wiki/GitCommitMessages
Chromium - Contributing code http://www.chromium.org/**developers/contributing-codehttp://www.chromium.org/developers/contributing-code
Qt - Introduction to Gerrit http://qt-project.org/wiki/**Gerrit-Introductionhttp://qt-project.org/wiki/Gerrit-Introduction
GNOME - a guide to writing git commit messages http://blogs.gnome.org/danni/**2011/10/25/a-guide-to-writing-** git-commit-messages/http://blogs.gnome.org/danni/2011/10/25/a-guide-to-writing-git-commit-messages/
EGit - Contributor Guide http://wiki.eclipse.org/EGit/**Contributor_Guidehttp://wiki.eclipse.org/EGit/Contributor_Guide
Gerrit Code Review - Contributing https://gerrit-review.**googlesource.com/**Documentation/dev-** contributing.htmlhttps://gerrit-review.googlesource.com/Documentation/dev-contributing.html
Proper Git Commit Messages and an Elegant Git History http://ablogaboutcode.com/**2011/03/23/proper-git-commit-** messages-and-an-elegant-git-**history/http://ablogaboutcode.com/2011/03/23/proper-git-commit-messages-and-an-elegant-git-history/
-- Quim Gil Technical Contributor Coordinator @ Wikimedia Foundation http://www.mediawiki.org/wiki/**User:Qgilhttp://www.mediawiki.org/wiki/User:Qgil
______________________________**_________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/**mailman/listinfo/wikitech-lhttps://lists.wikimedia.org/mailman/listinfo/wikitech-l
On 01/03/13 23:59, Daniel Friesen wrote:
On Fri, 01 Mar 2013 14:45:14 -0800, Nischay Nahata wrote
I also prefer it in the header. The bug report is the best description :)
Is it not possible for Gerrit to search if its in the header? or make it so
+1
Tools should be coded around people. Not the other way around.
+1
Chad wrote:
No, Gerrit cannot detect these in the header.
It should learn to do it.
Re: Quim Gil: [[Gerrit/Commit message guidelines]] should be changed, too.
On 03/01/2013 01:46 PM, Chad wrote:
Hi,
This is a friendly reminder to everyone about the preferred way to link to bugs in your commit messages.
As specified at
https://www.mediawiki.org/wiki/Gerrit/Commit_message_guidelines
Eyes on this page & edits (if needed) are welcome.
When you include them as part of the footer, they are indexed and are thus searchable. For example:
""" Fixing some weird bug
More explanation Blah blah blah.
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
On 1 March 2013 23:46, Chad innocentkiller@gmail.com wrote:
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
Few questions:
1) Why is "Bug:43778" different from "bug:43778" when searching?
2) Can we do the same for all things in the footer? I tried it but "bug" seems to be a special case and nothing else works.
-Niklas
On 20/03/13 11:59, Niklas Laxström wrote:
Why is "Bug:43778" different from "bug:43778" when searching?
Can we do the same for all things in the footer? I tried it but
"bug" seems to be a special case and nothing else works.
The "stored things" are set in gerrit config.
On Mar 20, 2013, at 11:59 AM, Niklas Laxström niklas.laxstrom@gmail.com wrote:
On 1 March 2013 23:46, Chad innocentkiller@gmail.com wrote:
Bug: 1234 Change-Id: Ia90..... """
So when you do this, you're able to search for "bug:1234" via Gerrit. By doing this, you're also removing it from the first line (which was our old habit, mostly from SVN days), providing you more space to be descriptive in that first line.
Few questions:
- Why is "Bug:43778" different from "bug:43778" when searching?
Because it doesn't literally search for "Bug:123" (even though in our case it looks that way because the footer is also Bug: 123).
There is a search operator (bug), which is linked to a footer name (Bug:), a match ("\#?\d{1,6}") for the value that is to be indexed. Just like project, owner, branch and topic are search operators linked to certain values. The operators are case sensitive and always lowercase by convention.
The footer being clickable is done independently.
-- Krinkle
wikitech-l@lists.wikimedia.org