Merge errors in CHANGELOG

[Simon Schäfer]

Because we get a lot of merge errors in the new introduced CHANGELOG, I
want to suggest a different solution:

There is a directory called "changelogs" or something like that,
containing files with a single line, the message of the change. To avoid
duplications, the files can be named like the ticket numbers.

On a new release the content of the files can be merged with this simple
command:

ls -tr changelogs/* | (xargs cat >> CHANGELOG)

-tr sorts the files by their creation date (in reversed order), thus it
is always known which ticket are fixed first.

With the help of a script it should be easy to add entries and merge
them at the end.

What do you think, is it a practical solution?

Greetings,
Simon

[Luc Bourlier]

It is the great solution!!! I had the same idea on Friday :)

The answer I got from the other guys here in Lausanne was "meh".

It is true that using a CHANGELOG file doesn't work. We were planning to look at the way it is done for Scala. It is basically a mix of git log and issue tracker log, plus a hand written text pointing to the important changes. We need to see if we can reuse their tools without too much (/any) effort.

Luc

[Mirco Dotta]

It is the great solution!!! I had the same idea on Friday :)

The answer I got from the other guys here in Lausanne was "meh".

It is true that using a CHANGELOG file doesn't work. We were planning to look at the way it is done for Scala. It is basically a mix of git log and issue tracker log, plus a hand written text pointing to the important changes. We need to see if we can reuse their tools without too much (/any) effort.

Luc

Le mardi 22 janvier 2013 17:53:50 UTC+1, Simon Schäfer a écrit :

Because we get a lot of merge errors in the new introduced CHANGELOG, I
want to suggest a different solution:

Yep, the current way of handling this doesn't work.

I was hoping that adding the following .gitattributes (https://github.com/dotta/test-gitattributes/blob/master/.gitattributes) to the repository would have solved the issue, but it looks like the GitHub merge functionality does not consider .gitattributes :( (check the PR https://github.com/dotta/test-gitattributes/pull/1, the merge button is disabled). The good thing about the .gitattributes is that I can manually run the merge from command-line, i.e., the merge succeeds. Today I've sent an email to the GitHub folks to ask if there is any alternative way to make this working.

There is a directory called "changelogs" or something like that,
containing files with a single line, the message of the change. To avoid
duplications, the files can be named like the ticket numbers.

On a new release the content of the files can be merged with this simple
command:

ls -tr changelogs/* | (xargs cat >> CHANGELOG)

-tr sorts the files by their creation date (in reversed order), thus it
is always known which ticket are fixed first.

With the help of a script it should be easy to add entries and merge
them at the end.

What do you think, is it a practical solution?

Pragmatic and it would work. Furthermore, I don't exactly recall why I was against it :). So, if there is no real alternative to the .gitattributes, I'm ok with what you guys suggested.

-- Mirco

[iulian dragos]

I am not fond of this solution, what do we do with all these files after a release? Consolidate them in an old CHANGELOG, and delete the rest?

For the last milestone it took me around 15 min to curate the changelog, so I have the feeling we're overengineering here. I'd say, if there's no way to fix merge conflicts at the tool level we should go back to manual changelogs.

iulian

 

-- Mirco

--
« Je déteste la montagne, ça cache le paysage »
Alphonse Allais

[Mirco Dotta]

On Jan 22, 2013, at 9:35 PM, iulian dragos wrote:

On Tue, Jan 22, 2013 at 7:30 PM, Mirco Dotta <mirco...@typesafe.com> wrote:

It is the great solution!!! I had the same idea on Friday :)

The answer I got from the other guys here in Lausanne was "meh".

It is true that using a CHANGELOG file doesn't work. We were planning to look at the way it is done for Scala. It is basically a mix of git log and issue tracker log, plus a hand written text pointing to the important changes. We need to see if we can reuse their tools without too much (/any) effort.

Luc

Le mardi 22 janvier 2013 17:53:50 UTC+1, Simon Schäfer a écrit :

Because we get a lot of merge errors in the new introduced CHANGELOG, I
want to suggest a different solution:

Yep, the current way of handling this doesn't work.

I was hoping that adding the following .gitattributes (https://github.com/dotta/test-gitattributes/blob/master/.gitattributes) to the repository would have solved the issue, but it looks like the GitHub merge functionality does not consider .gitattributes :( (check the PR https://github.com/dotta/test-gitattributes/pull/1, the merge button is disabled). The good thing about the .gitattributes is that I can manually run the merge from command-line, i.e., the merge succeeds. Today I've sent an email to the GitHub folks to ask if there is any alternative way to make this working.

There is a directory called "changelogs" or something like that,
containing files with a single line, the message of the change. To avoid
duplications, the files can be named like the ticket numbers.

On a new release the content of the files can be merged with this simple
command:

ls -tr changelogs/* | (xargs cat >> CHANGELOG)

-tr sorts the files by their creation date (in reversed order), thus it
is always known which ticket are fixed first.

With the help of a script it should be easy to add entries and merge
them at the end.

What do you think, is it a practical solution?

Pragmatic and it would work. Furthermore, I don't exactly recall why I was against it :). So, if there is no real alternative to the .gitattributes, I'm ok with what you guys suggested.

I am not fond of this solution, what do we do with all these files after a release? Consolidate them in an old CHANGELOG, and delete the rest?

Nope. We would run Simon's command for generating the aggregated CHANGELOG for the current release, drop the output here https://github.com/scala-ide/docs/blob/master/src/sphinx/changelog.rst, and delete all files in the "changelogs" directory.

For the last milestone it took me around 15 min to curate the changelog, so I have the feeling we're overengineering here.

Cutting a release already involves enough manual steps, and creating the changelog manually is one of this things I would really not mind to avoid. If .gitattributes (or similar) don't work out (I haven't yet got an answer from GitHub, but I have very low expectation this will work), then Simon's suggestion is the one that requires less effort on our side. The only cleaner alternative I see is to use the commit message for generating the changelog, just like it's done in the Scala project (we will have to create a script for parsing the commit messages, but that is simple to achieve). What this practically means is that the commit message's title will be used for generating the changelog. Here follows an example of a commit message

---------------------------------------------------

Fix #TicketNumber [short description]

[Long description]

---------------------------------------------------

I think we should strive for a title that has less than 80 characters (but without getting nuts about this ;)). And, I'd not be surprised if the short description in the title matches the ticket's title, in most of the cases.

-- Mirco

P.S. Once we agree on the format, I'll update the project's README: we really need the developers guideline to be there.

I'd say, if there's no way to fix merge conflicts at the tool level we should go back to manual changelogs.

iulian

 

-- Mirco

--
« Je déteste la montagne, ça cache le paysage »
Alphonse Allais

---------------

Mirco Dotta

Typesafe - The software stack for applications that scale

PSE-D, 1015 Lausanne, Switzerland

Work: +41 (0)21 691 49 65

Twitter: @mircodotta

[iulian dragos]

So more manual work for a release :)

I am all for automation, but we should target the real time wasters. If engineering this solution takes 2 days for an engineer, and doing it manually is (generously speaking) 30 min/release, we need quite a number of releases to amortize the effort (we had 3 milestones in 2012, let's say we get to double that in 2013). We tried a simple thing, it turned out not to work, it's fine to take a step back and re-asses how much of a problem this really is.

 

For the last milestone it took me around 15 min to curate the changelog, so I have the feeling we're overengineering here.

Cutting a release already involves enough manual steps, and creating the changelog manually is one of this things I would really not mind to avoid. If .gitattributes (or similar) don't work out (I haven't yet got an answer from GitHub, but I have very low expectation this will work), then Simon's suggestion is the one that requires less effort on our side. The only cleaner alternative I see is to use the commit message for generating the changelog, just like it's done in the Scala project (we will have to create a script for parsing the commit messages, but that is simple to achieve). What this practically means is that the commit message's title will be used for generating the changelog. Here follows an example of a commit message

---------------------------------------------------

Fix #TicketNumber [short description]

[Long description]

---------------------------------------------------

I think we should strive for a title that has less than 80 characters (but without getting nuts about this ;)). And, I'd not be surprised if the short description in the title matches the ticket's title, in most of the cases.

-- Mirco

P.S. Once we agree on the format, I'll update the project's README: we really need the developers guideline to be there.

I'd say, if there's no way to fix merge conflicts at the tool level we should go back to manual changelogs.

iulian

 

-- Mirco

--
« Je déteste la montagne, ça cache le paysage »
Alphonse Allais

---------------

Mirco Dotta

Typesafe - The software stack for applications that scale

PSE-D, 1015 Lausanne, Switzerland

Work: +41 (0)21 691 49 65

Twitter: @mircodotta

[Simon Schäfer]

I don't expect that this solutions takes more than a hour to be
developed. Just writing a little script with two commands:

# adding new ticket
$ ./changelogs -a <ticket> <description>
# merging tickets
$ ./changelogs -m <output>

Even with some security queries inside of the script, it contains just
some simple control flow.

> Typesafe <http://www.typesafe.com/> - The software stack for

> applications that scale
> PSE-D, 1015 Lausanne, Switzerland

> Work: +41 (0)21 691 49 65 <tel:%2B41%20%280%2921%20691%2049%2065>

[Mirco Dotta]

Nope. We would run Simon's command for generating the aggregated CHANGELOG for the current release, drop the output here https://github.com/scala-ide/docs/blob/master/src/sphinx/changelog.rst, and delete all files in the "changelogs" directory.

So more manual work for a release :)

I am all for automation, but we should target the real time wasters. If engineering this solution takes 2 days for an engineer, and doing it manually is (generously speaking) 30 min/release, we need quite a number of releases to amortize the effort (we had 3 milestones in 2012, let's say we get to double that in 2013). We tried a simple thing, it turned out not to work, it's fine to take a step back and re-asses how much of a problem this really is.

Then why not embedding the information in the commit message as I suggested in my past email? What's the arm? None has to work on creating the script today, and you can still do it manually if you find it's faster. I really can't see how this would be over-engineering...

[Mirco Dotta]

Just got an answer from GitHub about .gitattributes, and they are currently not supported. 

So, what do we do? Is anyone against having the information embedded in the first line of the commit message (as I described in one of my previous emails)?

-- Mirco

[Mirco Dotta]

On Jan 23, 2013, at 4:14 PM, Mirco Dotta wrote:

Just got an answer from GitHub about .gitattributes, and they are currently not supported. 

So, what do we do? Is anyone against having the information embedded in the first line of the commit message (as I described in one of my previous emails)?

I just opened a PR for embedding the developers guidelines in our README https://github.com/scala-ide/scala-ide/pull/283

Maybe it's a good moment for moving the discussion there.

[iulian dragos]

On Wed, Jan 23, 2013 at 11:20 AM, Mirco Dotta <mirco...@typesafe.com> wrote:

Nope. We would run Simon's command for generating the aggregated CHANGELOG for the current release, drop the output here https://github.com/scala-ide/docs/blob/master/src/sphinx/changelog.rst, and delete all files in the "changelogs" directory.

So more manual work for a release :)

I am all for automation, but we should target the real time wasters. If engineering this solution takes 2 days for an engineer, and doing it manually is (generously speaking) 30 min/release, we need quite a number of releases to amortize the effort (we had 3 milestones in 2012, let's say we get to double that in 2013). We tried a simple thing, it turned out not to work, it's fine to take a step back and re-asses how much of a problem this really is.

Then why not embedding the information in the commit message as I suggested in my past email? What's the arm? None has to work on creating the script today, and you can still do it manually if you find it's faster. I really can't see how this would be over-engineering...

The first line of the commit message, or pull request? Do you mention all tickets (sometimes it's more than one) on the first line, and if you do, you need to repeat "Fix " before each one (for Assembla to close the ticket), or it works with just "Fix #100, #101, #102"? 

 

--
 
 

[Mirco Dotta]

On Jan 23, 2013, at 4:44 PM, iulian dragos wrote:

On Wed, Jan 23, 2013 at 11:20 AM, Mirco Dotta <mirco...@typesafe.com> wrote:

Nope. We would run Simon's command for generating the aggregated CHANGELOG for the current release, drop the output here https://github.com/scala-ide/docs/blob/master/src/sphinx/changelog.rst, and delete all files in the "changelogs" directory.

So more manual work for a release :)

I am all for automation, but we should target the real time wasters. If engineering this solution takes 2 days for an engineer, and doing it manually is (generously speaking) 30 min/release, we need quite a number of releases to amortize the effort (we had 3 milestones in 2012, let's say we get to double that in 2013). We tried a simple thing, it turned out not to work, it's fine to take a step back and re-asses how much of a problem this really is.

Then why not embedding the information in the commit message as I suggested in my past email? What's the arm? None has to work on creating the script today, and you can still do it manually if you find it's faster. I really can't see how this would be over-engineering...

The first line of the commit message, or pull request?

The commit message

Do you mention all tickets (sometimes it's more than one) on the first line, and if you do, you need to repeat "Fix " before each one (for Assembla to close the ticket), or it works with just "Fix #100, #101, #102"? 

Good point. I can't find any indication that it works without repeating the Fix prefix. I agree it's not ideal to start a commit message with list of Fix #XXX (though, that doesn't happen that often). An alternative is to put it at the end of the title, i.e., [description] Fix #XXX, Fix #YYY

--
 
 

[François Garillot]

iulian dragos murmured on Bahman 3, 1391:

> I am not fond of this solution, what do we do with all these files after a
> release? Consolidate them in an old CHANGELOG, and delete the rest?

Let's just version the big CHANGELOG file itself when we cut a
release (the branch of the release should not contain changefiles beyond
what we want to include).

The following command lists the files of the changelog/ repository,
newer than the CHANGELOG-2.02-RC7 file, from the most to the least
recent:

find ~/path/to/changelog -newer ~/path/to/CHANGELOG-2.02-RC7 -type f -printf '%T@ %f\n' | sort -nr | awk '{$1=""; print $0}'

--
FG