One thing I've noticed in the last couple of days of madly reviewing things in gerrit is that merge conflicts in the RELEASE-NOTES-1.20 file are very common.
Because of the delay between submission and post-review merge, there's a high probability that a new entry in one of the sections of RELEASE-NOTES-1.20 will "conflict" with entries added by other commits that have been merged in the meantime. Git doesn't understand that it can just slip the line in at the end of the section, alas. :)
Do we really need to be maintaining these release notes files this way, though?
Now that we have pre-commit review, we can more aggressively police commit messages so that the first line is more consistently "release-notes-ready", and we can generate release-notes files from commit logs instead, and avoid the make-work of manually adding to and merging RELEASE-NOTES files on every change.
Thoughts? Concerns? Threats? :)
-- brion
2012/4/3 Brion Vibber brion@wikimedia.org:
Do we really need to be maintaining these release notes files this way, though?
Now that we have pre-commit review, we can more aggressively police commit messages so that the first line is more consistently "release-notes-ready", and we can generate release-notes files from commit logs instead, and avoid the make-work of manually adding to and merging RELEASE-NOTES files on every change.
Thoughts? Concerns? Threats? :)
+1, in general.
I was never sure what is worthy of putting in release notes. Sometimes people suggested me to put my changes there, so i did. At some point i started guessing myself.
It makes sense that only a small group of release management people will make significant changes to that file and i'll gladly adopt guidelines for commit messages that help them.
-- Amir Elisha Aharoni · אָמִיר אֱלִישָׁע אַהֲרוֹנִי http://aharoni.wordpress.com “We're living in pieces, I want to live in peace.” – T. Moore
On Tue, Apr 3, 2012 at 4:29 PM, Brion Vibber brion@wikimedia.org wrote:
One thing I've noticed in the last couple of days of madly reviewing things in gerrit is that merge conflicts in the RELEASE-NOTES-1.20 file are very common.
Because of the delay between submission and post-review merge, there's a high probability that a new entry in one of the sections of RELEASE-NOTES-1.20 will "conflict" with entries added by other commits that have been merged in the meantime. Git doesn't understand that it can just slip the line in at the end of the section, alas. :)
Yeah. That was a problem in SVN and it's a problem in Git now too. The only difference was with SVN you had to fix the problem yourself before committing, whereas now you don't know until you attempt the merge. It's part of the fun ;-)
Do we really need to be maintaining these release notes files this way, though?
Now that we have pre-commit review, we can more aggressively police commit messages so that the first line is more consistently "release-notes-ready", and we can generate release-notes files from commit logs instead, and avoid the make-work of manually adding to and merging RELEASE-NOTES files on every change.
Thoughts? Concerns? Threats? :)
I like the idea in principle--it certainly will help reduce the number of silly conflicts we're stuck rebasing. The only thing I'd worry about is making sure that we enforce proper commit summary guidelines.
I'd be interested in seeing what the results roughly look like--I imagine it'd still need some manual wrangling before we publish them as final. In fact--you could submit the proposed release notes to the branch around the time we cut the first beta/rc, and they can be discussed/formatted/bikeshedded on gerrit.
-Chad
Why not just maintain them on MediaWiki.org? When you merge changes, simply add to the "Release notes/1.20" page. It might even be possible to automate that.
On 03/04/12 21:29, Brion Vibber wrote:
One thing I've noticed in the last couple of days of madly reviewing things in gerrit is that merge conflicts in the RELEASE-NOTES-1.20 file are very common.
Because of the delay between submission and post-review merge, there's a high probability that a new entry in one of the sections of RELEASE-NOTES-1.20 will "conflict" with entries added by other commits that have been merged in the meantime. Git doesn't understand that it can just slip the line in at the end of the section, alas. :)
Do we really need to be maintaining these release notes files this way, though?
Now that we have pre-commit review, we can more aggressively police commit messages so that the first line is more consistently "release-notes-ready", and we can generate release-notes files from commit logs instead, and avoid the make-work of manually adding to and merging RELEASE-NOTES files on every change.
Thoughts? Concerns? Threats? :)
-- brion _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Tue, 03 Apr 2012 13:29:44 -0700, Brion Vibber brion@wikimedia.org wrote:
One thing I've noticed in the last couple of days of madly reviewing things in gerrit is that merge conflicts in the RELEASE-NOTES-1.20 file are very common.
Because of the delay between submission and post-review merge, there's a high probability that a new entry in one of the sections of RELEASE-NOTES-1.20 will "conflict" with entries added by other commits that have been merged in the meantime. Git doesn't understand that it can just slip the line in at the end of the section, alas. :)
Do we really need to be maintaining these release notes files this way, though?
Now that we have pre-commit review, we can more aggressively police commit messages so that the first line is more consistently "release-notes-ready", and we can generate release-notes files from commit logs instead, and avoid the make-work of manually adding to and merging RELEASE-NOTES files on every change.
Thoughts? Concerns? Threats? :)
-- brion
We have a policy of restricting the length of the first line. Since it's used by gerrit as email subjects. So as a result when I write the first line of a git commit I inevitably leave out critical information. So the first line of a commit misses out information that if I had a RELEASE-NOTES line to write would be in there.
Also, I've noticed that a decent portion of my commits are small backend stuff or modifications. Stuff which have little business being inside RELEASE-NOTES. Frankly if we do it that way RELEASE-NOTES becomes little more than a commit log, which is a lot less valuable than the RELEASE-NOTES we currently have.
On 04/04/12 10:31, Daniel Friesen wrote:
We have a policy of restricting the length of the first line. Since it's used by gerrit as email subjects. So as a result when I write the first line of a git commit I inevitably leave out critical information. So the first line of a commit misses out information that if I had a RELEASE-NOTES line to write would be in there.
Also, I've noticed that a decent portion of my commits are small backend stuff or modifications. Stuff which have little business being inside RELEASE-NOTES. Frankly if we do it that way RELEASE-NOTES becomes little more than a commit log, which is a lot less valuable than the RELEASE-NOTES we currently have.
I agree with this. Usually I target commit messages at developers and release notes messages at users. Sometimes that means that the two texts have nothing in common at all.
I think the release notes could go further down in the commit message, perhaps with a footer style similar to Gerrit's Change-Id, for example:
Refactored Foo.php, splitting animal classes from vegetable classes
* Used closures for EVERYTHING * (bug 98765) Fixed a spelling error in a CSS class name
Release-Notes: (bug 98765) Renamed CSS class .foo-arbitary to .foo-arbitrary
-- Tim Starling
On Tue, Apr 3, 2012 at 9:24 PM, Tim Starling tstarling@wikimedia.org wrote:
On 04/04/12 10:31, Daniel Friesen wrote:
We have a policy of restricting the length of the first line. Since it's used by gerrit as email subjects. So as a result when I write the first line of a git commit I inevitably leave out critical information. So the first line of a commit misses out information that if I had a RELEASE-NOTES line to write would be in there.
Also, I've noticed that a decent portion of my commits are small backend stuff or modifications. Stuff which have little business being inside RELEASE-NOTES. Frankly if we do it that way RELEASE-NOTES becomes little more than a commit log, which is a lot less valuable than the RELEASE-NOTES we currently have.
I agree with this. Usually I target commit messages at developers and release notes messages at users. Sometimes that means that the two texts have nothing in common at all.
I think the release notes could go further down in the commit message, perhaps with a footer style similar to Gerrit's Change-Id, for example:
Refactored Foo.php, splitting animal classes from vegetable classes
- Used closures for EVERYTHING
- (bug 98765) Fixed a spelling error in a CSS class name
Release-Notes: (bug 98765) Renamed CSS class .foo-arbitary to .foo-arbitrary
+1
-Chad
On Tue, 03 Apr 2012 18:24:03 -0700, Tim Starling tstarling@wikimedia.org wrote:
On 04/04/12 10:31, Daniel Friesen wrote:
We have a policy of restricting the length of the first line. Since it's used by gerrit as email subjects. So as a result when I write the first line of a git commit I inevitably leave out critical information. So the first line of a commit misses out information that if I had a RELEASE-NOTES line to write would be in there.
Also, I've noticed that a decent portion of my commits are small backend stuff or modifications. Stuff which have little business being inside RELEASE-NOTES. Frankly if we do it that way RELEASE-NOTES becomes little more than a commit log, which is a lot less valuable than the RELEASE-NOTES we currently have.
I agree with this. Usually I target commit messages at developers and release notes messages at users. Sometimes that means that the two texts have nothing in common at all.
I think the release notes could go further down in the commit message, perhaps with a footer style similar to Gerrit's Change-Id, for example:
Refactored Foo.php, splitting animal classes from vegetable classes
- Used closures for EVERYTHING
- (bug 98765) Fixed a spelling error in a CSS class name
Release-Notes: (bug 98765) Renamed CSS class .foo-arbitary to .foo-arbitrary
-- Tim Starling
Another two related things I found:
Firstly: http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-chan... A git merge that seams to understand how to intelligently merge some types of changelog files. I thought this might be problematic to have everyone install. But thinking about it again. Gerrit is the one doing merges. If that can handle the RELEASE-NOTES format that we uses. Then theoretically installing it on the server gerrit uses and then configuring our release notes to use it could theoretically make Gerrit suddenly able to handle RELEASE-NOTES changes without conflicts.
And on release notes inside commit, another option: Using a 'release-notes' git notes namespace. http://progit.org/2010/08/25/notes.html
It has a disadvantage in the area of ease of use. (It'll be another thing that'll probably need another tweak to git-review) But it has the advantage that you can edit notes after commit without having to amend the code.
On 05/04/12 10:53, Daniel Friesen wrote:
Firstly: http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-chan...
A git merge that seams to understand how to intelligently merge some types of changelog files. I thought this might be problematic to have everyone install. But thinking about it again. Gerrit is the one doing merges. If that can handle the RELEASE-NOTES format that we uses. Then theoretically installing it on the server gerrit uses and then configuring our release notes to use it could theoretically make Gerrit suddenly able to handle RELEASE-NOTES changes without conflicts.
I like it.
wikitech-l@lists.wikimedia.org