A request: Moving away from ChangeLog

A request: Moving away from ChangeLog

[John Wiegley]

The Emacs ChangeLog is a file which predates the existence of freely available, project-wide version control.  It was a way to see, in one place, the stream of changes occurring in a project -- something which RCS could not do for you.

However, in this modern era of project-wide, atomic commits, the ChangeLog is not only an archaism, but is a continuous source of merge conflicts.  For example, when I reverted Russell's latest change -- a one-liner that was minor in the extreme -- I had to do with a merge conflict in lisp/ChangeLog.

With a system like Git, and properly written commits, you can produce a ChangeLog at any time with "git log".  You even see a ChangeLog for just one file, or a directory with "git log --follow PATH".  This completes supersedes any need for a ChangeLog file, and has led me to abandon the use of ChangeLogs in all the projects I maintain.

I would request we do so for Org-mode as well, unless there is some compelling reason to keep this file.

John

Re: A request: Moving away from ChangeLog

[John Wiegley]

I just remembered that I'd written a script for building a properly formatted ChangeLog directly from Git history:

    http://github.com/jwiegley/git-scripts/blob/master/git-changelog

This makes it trivial to build ChangeLog entries for a range of commits, suitable for submission to Emacs.  It may need a bit more work to be production-ready, but it can already produce a ChangeLog for all of org-mode.

John

Re: Re: A request: Moving away from ChangeLog

[Carsten Dominik]

On May 21, 2010, at 11:41 AM, John Wiegley wrote:

> I just remembered that I'd written a script for building a properly  
> formatted ChangeLog directly from Git history:
>
>    http://github.com/jwiegley/git-scripts/blob/master/git-changelog
>
> This makes it trivial to build ChangeLog entries for a range of  
> commits, suitable for submission to Emacs.  It may need a bit more  
> work to be production-ready, but it can already produce a ChangeLog  
> for all of org-mode.

If that is a possibility, then I am all game.  The ONLY reason why I  
was making these entries is because Emacs requires me to make them.   
If we can use a script to create it just for the moment when we sync  
up with Emacs - GREAT.

Can I have a look at one of those ChangeLog files created with the  
script?  Just to get the idea?  Do we need to do something special in  
the git commit message?

If this works, lets stop writing ChangeLog.

This will make most merges working without hickups, finally.  And it  
will make us, hopefully, write better commit messages.

- Carsten

Re: Re: A request: Moving away from ChangeLog

[John Wiegley]

On May 21, 2010, at 8:15 AM, Carsten Dominik wrote:

> Can I have a look at one of those ChangeLog files created with the script?  Just to get the idea?  Do we need to do something special in the git commit message?

Below is output from running "git changelog HEAD~15.. -- lisp".  It can identify the files that changed automatically, but not functions; such information has to be present in the commit description.

I propose the following standard for commit entries, around which I can adapt the script for future entries.  This standard is based on the one found in the git-commit man page:

  Line 1 is a <50 character short description

  Line 3 starts a 72-column full commit entry, formatted just like a
  ChangeLog entry, but without leading whitespace or '*'.  If a changed
  file is mentioned, the mention isn't repeated by git-changelog; but
  if it's not mentioned, it gets added automatically to the generated
  ChangeLog.

  Further, I will change the tool to pay attention to relative directory
  names so that when we generate log entries for "lisp", no "lisp/"
  prefixes are given to any auto-added filenames.

John

2010-05-21  John Wiegley  <johnw@newartisans.com>

	* lisp/ChangeLog, lisp/org.el: Revert "org.el
	(org-remove-inline-images): Call `clear-image-cache'."
	
	This reverts commit 0c42220ca025269e39f20191bc3e10d6b55d02ac.

2010-05-21  Carsten Dominik  <carsten.dominik@gmail.com>

	* lisp/ChangeLog, lisp/org.el: Document the match groups
	of org-emph-re

2010-05-20  Bernt Hansen  <bernt@norang.ca>

	* lisp/ChangeLog, lisp/org-clock.el: Set `org-clock-clocking-in'
	to t before `org-clock-out'

2010-05-20  Russell Adams  <RLAdams@AdamsInfoServ.Com>

	* lisp/ChangeLog, lisp/org.el: org.el (org-remove-inline-images):
	Call `clear-image-cache'.

2010-05-20  Bastien Guerry  <bzg@altern.org>

	* lisp/org-timer.el: Use the type "number" for the new
	variable org-timer-default-timer

2010-05-20  Bastien Guerry  <bzg@altern.org>

	* lisp/ChangeLog, lisp/org-timer.el: Define and use a new
	variable: org-timer-default-timer
	
	This variable defaults to nil.  When non-nil, this is the default
	value when the user is prompted for a timer.
	
	This patch also improves org-timer-set-timer so that the user can
	replace the current timer by a new one.

2010-05-06  Thomas Morgan  <tlm@ziiuu.com>

	* lisp/org-agenda.el: Persistent filters in Org mode
	
	Hello, Org mode hackers,
	
	This patch defines a variable `org-agenda-persistent-filters'.
	When it is set, filters persist from one agenda view to the next.
	
	I've found this convenient when using tags for contexts like @home,
	@net, etc., some of which commonly remain applicable for a while.
	
	Thanks,
	Thomas
	
	From 052ef9205845c78cb24d6fea8f89484bbe12a528 Mon Sep 17 00:00:00 2001
	From: Thomas Morgan <tlm@ziiuu.com>
	Date: Fri, 23 Apr 2010 11:48:03 +0200
	Subject: [PATCH] New option `org-agenda-persistent-filters'.
	 When set, keep filters from one agenda view to the next.

2010-05-20  Carsten Dominik  <carsten.dominik@gmail.com>

	* lisp/ChangeLog, lisp/org.el: Hide subtree before exposing
	the headings with `C-c C-k'
	
	Proposed by Ali Tofigh.
	
	Now `C-c C-k' always creates the same view, independent of what the
	subtree visibility was before.

2010-05-19  David Maus  <dmaus@ictsoc.de>

	* lisp/ChangeLog, lisp/org.el: Remove empty property drawers
	in cloned subtrees.

2010-05-19  David Maus  <dmaus@ictsoc.de>

	* lisp/ChangeLog, lisp/org.el: Provide customization variable
	`org-clone-delete-id'.
	
	When non-nil, clones of a subtree don't inherit the ID property.
	Otherwise they do and it will be set to a new unique identifier.

2010-05-19  David Maus  <dmaus@ictsoc.de>

	* lisp/ChangeLog, lisp/org.el: Maybe create ID property in
	cloned subtrees.

2010-05-19  Carsten Dominik  <carsten.dominik@gmail.com>

	* lisp/org.el: Add Anthony Lander's org-mac-link-grabber.el

2010-05-19  Carsten Dominik  <carsten.dominik@gmail.com>

	* lisp/ChangeLog, lisp/org.el: Fix empty-line problem after
	repeating entry
	
	Tom writes:
	
	> if I have a heading like this:
	>
	>
	> ** TODO test task
	> stuff
	>  SCHEDULED: <2010-05-15 Sat 07:35 +1d>
	>
	>
	> Then an empty line is inserted below the heading (before "stuff") if
	> org-indent-mode is on and logging is set like this:
	>
	>
	> (setq org-log-repeat nil)
	> (setq org-log-done 'time)
	>
	>
	>
	> I tested it with a clean config using only the settings above.

2010-05-19  Carsten Dominik  <carsten.dominik@gmail.com>

	* lisp/ChangeLog, lisp/org.el: Merge branch 'master' of
	git+ssh://repo.or.cz/srv/git/org-mode
	
	Conflicts:
		lisp/ChangeLog

2010-05-19  Bastien Guerry  <bzg@altern.org>

	* lisp/ChangeLog, lisp/org.el: Fix `org-refile-cache-get'
	error.
	
	This patch fixes the problem first reported by Tassilo Horn in
	[mid:87y6fhxc47.fsf@thinkpad.tsdh.de].  Problem was that
	`org-refile-cache-get' returned an invalid refile target table after
	the refile cache was cleared.

Re: A request: Moving away from ChangeLog

[Ben Finney]

Carsten Dominik <carsten.dominik@gmail.com> writes:

> On May 21, 2010, at 11:41 AM, John Wiegley wrote:
> > This makes it trivial to build ChangeLog entries for a range of
> > commits, suitable for submission to Emacs. It may need a bit more
> > work to be production-ready, but it can already produce a ChangeLog
> > for all of org-mode.
[…]

> If this works, lets stop writing ChangeLog.

This is a great improvement.

It seems worth pointing out explicitly, though: Eliminating a
manually-maintained ChangeLog doesn't obviate the need for a ChangeLog
(or the equivalent) in the distributed source.

This is because the copyright holders license their works under the
GPLv2, and §2.a of those terms requires the work to include dated notice
of all modifications made to the work. This is conventionally understood
to be most directly satisfied by a ChangeLog in the distributed source
for the work.

Generating that file automatically from the VCS commit messages, at the
time a source release is packaged, is a good use of the VCS.

> This will make most merges working without hickups, finally.  And it
> will make us, hopefully, write better commit messages.

Indeed. Having one canonical location for a piece of information, with
every other instance of it derived from that location, can help reduce
the burden of recording that information.

-- 
 \       “I disapprove of what you say, but I will defend to the death |
  `\     your right to say it.” —Evelyn Beatrice Hall, _The Friends of |
_o__)                                                  Voltaire_, 1906 |
Ben Finney

Re: A request: Moving away from ChangeLog

[Tassilo Horn]

John Wiegley <jwiegley@gmail.com> writes:

Hi John,

>   Line 1 is a <50 character short description
>
>   Line 3 starts a 72-column full commit entry, formatted just like a
>   ChangeLog entry, but without leading whitespace or '*'.  If a changed
>   file is mentioned, the mention isn't repeated by git-changelog; but
>   if it's not mentioned, it gets added automatically to the generated
>   ChangeLog.

I think it would be better if line 3+ would be exact ChangeLog entries
format-wise, so that you can still use emacs' ChangeLog facilities
(`add-change-log-entry').  I don't really want to write the changed file
and function names on my own, and adding them correctly is exactly what
that function does very well.

Bye,
Tassilo

Re: Re: A request: Moving away from ChangeLog

[Carsten Dominik]

Hi Ben,

On May 21, 2010, at 3:01 PM, Ben Finney wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>
>> On May 21, 2010, at 11:41 AM, John Wiegley wrote:
>>> This makes it trivial to build ChangeLog entries for a range of
>>> commits, suitable for submission to Emacs. It may need a bit more
>>> work to be production-ready, but it can already produce a ChangeLog
>>> for all of org-mode.
> […]
>
>> If this works, lets stop writing ChangeLog.
>
> This is a great improvement.
>
> It seems worth pointing out explicitly, though: Eliminating a
> manually-maintained ChangeLog doesn't obviate the need for a ChangeLog
> (or the equivalent) in the distributed source.
>
> This is because the copyright holders license their works under the
> GPLv2, and §2.a of those terms requires the work to include dated  
> notice
> of all modifications made to the work. This is conventionally  
> understood
> to be most directly satisfied by a ChangeLog in the distributed source
> for the work.

I did not know this, thank you for making me aware of it.

- Carsten

>
> Generating that file automatically from the VCS commit messages, at  
> the
> time a source release is packaged, is a good use of the VCS.
>
>> This will make most merges working without hickups, finally.  And it
>> will make us, hopefully, write better commit messages.
>
> Indeed. Having one canonical location for a piece of information, with
> every other instance of it derived from that location, can help reduce
> the burden of recording that information.
>
> -- 
> \       “I disapprove of what you say, but I will defend to the  
> death |
>  `\     your right to say it.” —Evelyn Beatrice Hall, _The Friends  
> of |
> _o__)                                                  Voltaire_,  
> 1906 |
> Ben Finney
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten

Re: Re: A request: Moving away from ChangeLog

[Carsten Dominik]

On May 21, 2010, at 2:50 PM, John Wiegley wrote:

> On May 21, 2010, at 8:15 AM, Carsten Dominik wrote:
>
>> Can I have a look at one of those ChangeLog files created with the  
>> script?  Just to get the idea?  Do we need to do something special  
>> in the git commit message?
>
> Below is output from running "git changelog HEAD~15.. -- lisp".  It  
> can identify the files that changed automatically, but not  
> functions; such information has to be present in the commit  
> description.
>
> I propose the following standard for commit entries, around which I  
> can adapt the script for future entries.  This standard is based on  
> the one found in the git-commit man page:
>
>  Line 1 is a <50 character short description
>
>  Line 3 starts a 72-column full commit entry, formatted just like a
>  ChangeLog entry, but without leading whitespace or '*'.  If a changed
>  file is mentioned, the mention isn't repeated by git-changelog; but
>  if it's not mentioned, it gets added automatically to the generated
>  ChangeLog.
>
>  Further, I will change the tool to pay attention to relative  
> directory
>  names so that when we generate log entries for "lisp", no "lisp/"
>  prefixes are given to any auto-added filenames.

Well, now I am getting really annoyed - with myself.  This is
such an obvious, beautiful solution.  Why I did not think of
this several year ago is beyond me.  Lets do it like this.

Tassilo (separate message) does have a point though, that
it would be good to b able to use the ChangeLog tools to
create the ChangeLog-like entry.
On the other hand, the information about the committer is
something that would be really duplicate.

We need to think about a good solution here.

One possibility would be the following:

We use .gitignore to exclude ChangeLog from git processing.
His would mean that this file becomes some kind of scratch file.
You could use it to create the ChangeLog entries in the normal
way, using the existing Emacs functionality.  Then, when you are
ready to commit, you cut and paste into the commit message buffer.
We could even make a command for this, and apply any wanted
formatting like what John was proposing (removing the committer
line and indentation)...

I think that this is not a bad idea, because normally you will
not have the commit message buffer open while working on your
patch - so collecting ChangeLog info in a scratch file sounds
like a useful idea to me.

Other ideas?

- Carsten



>
> John
>
> 2010-05-21  John Wiegley  <johnw@newartisans.com>
>
> 	* lisp/ChangeLog, lisp/org.el: Revert "org.el
> 	(org-remove-inline-images): Call `clear-image-cache'."
> 	
> 	This reverts commit 0c42220ca025269e39f20191bc3e10d6b55d02ac.
>
> 2010-05-21  Carsten Dominik  <carsten.dominik@gmail.com>
>
> 	* lisp/ChangeLog, lisp/org.el: Document the match groups
> 	of org-emph-re
>
> 2010-05-20  Bernt Hansen  <bernt@norang.ca>
>
> 	* lisp/ChangeLog, lisp/org-clock.el: Set `org-clock-clocking-in'
> 	to t before `org-clock-out'
>
> 2010-05-20  Russell Adams  <RLAdams@AdamsInfoServ.Com>
>
> 	* lisp/ChangeLog, lisp/org.el: org.el (org-remove-inline-images):
> 	Call `clear-image-cache'.
>
> 2010-05-20  Bastien Guerry  <bzg@altern.org>
>
> 	* lisp/org-timer.el: Use the type "number" for the new
> 	variable org-timer-default-timer
>
> 2010-05-20  Bastien Guerry  <bzg@altern.org>
>
> 	* lisp/ChangeLog, lisp/org-timer.el: Define and use a new
> 	variable: org-timer-default-timer
> 	
> 	This variable defaults to nil.  When non-nil, this is the default
> 	value when the user is prompted for a timer.
> 	
> 	This patch also improves org-timer-set-timer so that the user can
> 	replace the current timer by a new one.
>
> 2010-05-06  Thomas Morgan  <tlm@ziiuu.com>
>
> 	* lisp/org-agenda.el: Persistent filters in Org mode
> 	
> 	Hello, Org mode hackers,
> 	
> 	This patch defines a variable `org-agenda-persistent-filters'.
> 	When it is set, filters persist from one agenda view to the next.
> 	
> 	I've found this convenient when using tags for contexts like @home,
> 	@net, etc., some of which commonly remain applicable for a while.
> 	
> 	Thanks,
> 	Thomas
> 	
> 	From 052ef9205845c78cb24d6fea8f89484bbe12a528 Mon Sep 17 00:00:00  
> 2001
> 	From: Thomas Morgan <tlm@ziiuu.com>
> 	Date: Fri, 23 Apr 2010 11:48:03 +0200
> 	Subject: [PATCH] New option `org-agenda-persistent-filters'.
> 	 When set, keep filters from one agenda view to the next.
>
> 2010-05-20  Carsten Dominik  <carsten.dominik@gmail.com>
>
> 	* lisp/ChangeLog, lisp/org.el: Hide subtree before exposing
> 	the headings with `C-c C-k'
> 	
> 	Proposed by Ali Tofigh.
> 	
> 	Now `C-c C-k' always creates the same view, independent of what the
> 	subtree visibility was before.
>
> 2010-05-19  David Maus  <dmaus@ictsoc.de>
>
> 	* lisp/ChangeLog, lisp/org.el: Remove empty property drawers
> 	in cloned subtrees.
>
> 2010-05-19  David Maus  <dmaus@ictsoc.de>
>
> 	* lisp/ChangeLog, lisp/org.el: Provide customization variable
> 	`org-clone-delete-id'.
> 	
> 	When non-nil, clones of a subtree don't inherit the ID property.
> 	Otherwise they do and it will be set to a new unique identifier.
>
> 2010-05-19  David Maus  <dmaus@ictsoc.de>
>
> 	* lisp/ChangeLog, lisp/org.el: Maybe create ID property in
> 	cloned subtrees.
>
> 2010-05-19  Carsten Dominik  <carsten.dominik@gmail.com>
>
> 	* lisp/org.el: Add Anthony Lander's org-mac-link-grabber.el
>
> 2010-05-19  Carsten Dominik  <carsten.dominik@gmail.com>
>
> 	* lisp/ChangeLog, lisp/org.el: Fix empty-line problem after
> 	repeating entry
> 	
> 	Tom writes:
> 	
> 	> if I have a heading like this:
> 	>
> 	>
> 	> ** TODO test task
> 	> stuff
> 	>  SCHEDULED: <2010-05-15 Sat 07:35 +1d>
> 	>
> 	>
> 	> Then an empty line is inserted below the heading (before "stuff")  
> if
> 	> org-indent-mode is on and logging is set like this:
> 	>
> 	>
> 	> (setq org-log-repeat nil)
> 	> (setq org-log-done 'time)
> 	>
> 	>
> 	>
> 	> I tested it with a clean config using only the settings above.
>
> 2010-05-19  Carsten Dominik  <carsten.dominik@gmail.com>
>
> 	* lisp/ChangeLog, lisp/org.el: Merge branch 'master' of
> 	git+ssh://repo.or.cz/srv/git/org-mode
> 	
> 	Conflicts:
> 		lisp/ChangeLog
>
> 2010-05-19  Bastien Guerry  <bzg@altern.org>
>
> 	* lisp/ChangeLog, lisp/org.el: Fix `org-refile-cache-get'
> 	error.
> 	
> 	This patch fixes the problem first reported by Tassilo Horn in
> 	[mid:87y6fhxc47.fsf@thinkpad.tsdh.de].  Problem was that
> 	`org-refile-cache-get' returned an invalid refile target table after
> 	the refile cache was cleared.
>
>

- Carsten

Re: Re: A request: Moving away from ChangeLog

[John Wiegley]

On May 21, 2010, at 9:47 AM, Tassilo Horn wrote:

> I think it would be better if line 3+ would be exact ChangeLog entries
> format-wise, so that you can still use emacs' ChangeLog facilities
> (`add-change-log-entry').  I don't really want to write the changed file
> and function names on my own, and adding them correctly is exactly what
> that function does very well.

This ends up looking rather ugly in the history, and I would hate to see VCS history bent merely to conform to tools usage.

Rather, the history should be as clean and exact as possible.  If elisp functions need to be written to convert ChangeLog entries to a suitable format, I can do that.

Also, in magit if you press 'C' on any diff hunk, it auto-generates a properly formatted ChangeLog-style comment into the current commit log.

John

Re: Re: A request: Moving away from ChangeLog

[John Wiegley]

On May 21, 2010, at 10:32 AM, Carsten Dominik wrote:

> We could even make a command for this, and apply any wanted
> formatting like what John was proposing (removing the committer
> line and indentation)...
> 
> I think that this is not a bad idea, because normally you will
> not have the commit message buffer open while working on your
> patch - so collecting ChangeLog info in a scratch file sounds
> like a useful idea to me.

I'm willing to write the necessary elisp code as a partner to the git-changelog script, so that they are kept in sync.

John

Re: Re: A request: Moving away from ChangeLog

[John Wiegley]

So, I suppose starting now we can just stop updating the ChangeLog.

Here is an example of how a properly formatted entry would become a commit message:

2010-05-19  David Maus  <dmaus@ictsoc.de>

	* org.el (org-refile-cache-get): Return empty list of targets
	when cache was cleared.
	(org-clone-subtree-with-time-shift): Maybe create ID property
	in cloned subtrees.
	(org-clone-delete-id): New customization variable.
	(org-clone-subtree-with-time-shift): Use customization
	variable `org-clone-delete-id'.
	(org-clone-subtree-with-time-shift): Remove empty property
	drawer in cloned subtrees.

Becomes:

Fixes to org-clone

* org.el (org-refile-cache-get): Return empty list of targets when cache
was cleared.
(org-clone-subtree-with-time-shift): Maybe create ID property in cloned
subtrees.
(org-clone-delete-id): New customization variable.
(org-clone-subtree-with-time-shift): Use customization variable
`org-clone-delete-id'.
(org-clone-subtree-with-time-shift): Remove empty property drawer in
cloned subtrees.

I guess having stars to indicate the different files is not bad.

John

Re: A request: Moving away from ChangeLog

[Bernt Hansen]

John Wiegley <jwiegley@gmail.com> writes:

> On May 21, 2010, at 9:47 AM, Tassilo Horn wrote:
>
>> I think it would be better if line 3+ would be exact ChangeLog entries
>> format-wise, so that you can still use emacs' ChangeLog facilities
>> (`add-change-log-entry').  I don't really want to write the changed file
>> and function names on my own, and adding them correctly is exactly what
>> that function does very well.
>
> This ends up looking rather ugly in the history, and I would hate to
> see VCS history bent merely to conform to tools usage.
>
> Rather, the history should be as clean and exact as possible.  If
> elisp functions need to be written to convert ChangeLog entries to a
> suitable format, I can do that.
>
> Also, in magit if you press 'C' on any diff hunk, it auto-generates a
> properly formatted ChangeLog-style comment into the current commit
> log.

I also prefer descriptive and succinct commit messages.

It should be possible to automatically retrieve function information and
other items from the source based on hunk line information and the
source code in a tool that builds the Changelog.

I make most of my git commits (including org-mode) in vim which is
kicked off from raw command-line git.  I normally make multiple changes
at once and then build separate commits by using git's editing hunk
features from 'git add -p'.  I don't think that functionality is
available in magit yet.

Requiring an elisp-only solution for making commits isn't ideal -- the
tools should be as flexible as possible.

I have no issue with the maintainers rejecting patches and requesting
changes to the commit messages so that they can be applied to the
project but I wouldn't want to require the use of a specific tool to do
the job.

Regards,
Bernt

Re: A request: Moving away from ChangeLog

[John Wiegley]

On May 21, 2010, at 11:39 AM, Bernt Hansen wrote:

> I make most of my git commits (including org-mode) in vim which is
> kicked off from raw command-line git.  I normally make multiple changes
> at once and then build separate commits by using git's editing hunk
> features from 'git add -p'.  I don't think that functionality is
> available in magit yet.

magit's original purpose was the ability to do just this.  So, it's been able to stage individual hunks since day one.  You can also use - and + to narrow or expand the range of each hunk.

John

Re: Re: A request: Moving away from ChangeLog

[Carsten Dominik]

On May 21, 2010, at 5:06 PM, John Wiegley wrote:

> On May 21, 2010, at 9:47 AM, Tassilo Horn wrote:
>
>> I think it would be better if line 3+ would be exact ChangeLog  
>> entries
>> format-wise, so that you can still use emacs' ChangeLog facilities
>> (`add-change-log-entry').  I don't really want to write the changed  
>> file
>> and function names on my own, and adding them correctly is exactly  
>> what
>> that function does very well.
>
> This ends up looking rather ugly in the history, and I would hate to  
> see VCS history bent merely to conform to tools usage.
>
> Rather, the history should be as clean and exact as possible.  If  
> elisp functions need to be written to convert ChangeLog entries to a  
> suitable format, I can do that.
>
> Also, in magit if you press 'C' on any diff hunk, it auto-generates  
> a properly formatted ChangeLog-style comment into the current commit  
> log.

But only the file, not the function...

- Carsten

Re: Re: A request: Moving away from ChangeLog

[John Wiegley]

On May 21, 2010, at 11:53 AM, Carsten Dominik wrote:

> But only the file, not the function...

I tested it with a function change, and it inserted the function name too!

John

Re: A request: Moving away from ChangeLog

[Bernt Hansen]

John Wiegley <jwiegley@gmail.com> writes:

> On May 21, 2010, at 11:39 AM, Bernt Hansen wrote:
>
>> I make most of my git commits (including org-mode) in vim which is
>> kicked off from raw command-line git.  I normally make multiple changes
>> at once and then build separate commits by using git's editing hunk
>> features from 'git add -p'.  I don't think that functionality is
>> available in magit yet.
>
> magit's original purpose was the ability to do just this.  So, it's
> been able to stage individual hunks since day one.  You can also use -
> and + to narrow or expand the range of each hunk.

Yes but... I can't edit those hunks and take this part but not that
part.  At least there was one case where 2 changes were on the same line
and I wanted to stage only the first edit for commit 1 and then stage
the second edit for commit 2.  I couldn't find a way to do this in magit.

If changes are isolated to single lines it works fine.  Now I have to
figure out how to specify emacsclient for my editor during rebase in
magit -- right now it fails to open the editor due to a wrong path and
bails.

Bernt

Re: Re: A request: Moving away from ChangeLog

[Eric Schulte]

Bernt Hansen <bernt@norang.ca> writes:

> John Wiegley <jwiegley@gmail.com> writes:
>
>> On May 21, 2010, at 9:47 AM, Tassilo Horn wrote:
>>
>>> I think it would be better if line 3+ would be exact ChangeLog entries
>>> format-wise, so that you can still use emacs' ChangeLog facilities
>>> (`add-change-log-entry').  I don't really want to write the changed file
>>> and function names on my own, and adding them correctly is exactly what
>>> that function does very well.
>>
>> This ends up looking rather ugly in the history, and I would hate to
>> see VCS history bent merely to conform to tools usage.
>>
>> Rather, the history should be as clean and exact as possible.  If
>> elisp functions need to be written to convert ChangeLog entries to a
>> suitable format, I can do that.
>>
>> Also, in magit if you press 'C' on any diff hunk, it auto-generates a
>> properly formatted ChangeLog-style comment into the current commit
>> log.
>
> I also prefer descriptive and succinct commit messages.
>
> It should be possible to automatically retrieve function information and
> other items from the source based on hunk line information and the
> source code in a tool that builds the Changelog.
>

Yes, `which-function' should be sufficient for collecting the names of
modified functions.

>
> I make most of my git commits (including org-mode) in vim which is
> kicked off from raw command-line git.  I normally make multiple changes
> at once and then build separate commits by using git's editing hunk
> features from 'git add -p'.  I don't think that functionality is
> available in magit yet.
>
> Requiring an elisp-only solution for making commits isn't ideal -- the
> tools should be as flexible as possible.
>
> I have no issue with the maintainers rejecting patches and requesting
> changes to the commit messages so that they can be applied to the
> project but I wouldn't want to require the use of a specific tool to do
> the job.
>

I think this could be a good candidate for a user-end pre-commit hook.
Since everyone on this project can be assumed to have a working Emacs
instillation it should be possible for git to run an elisp function
(through emacs --batch) before every commit which make the necessary
changelog changes (and possibly adds some key to the commit message
which could be checked by a gatekeeper commit-hook on the remote
repository to ensure compliance).

>
> Regards,
> Bernt
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: A request: Moving away from ChangeLog

[Christian Egli]

Hi all

John Wiegley <jwiegley@gmail.com> writes:

> The Emacs ChangeLog is a file which predates the existence of freely
> available, project-wide version control. It was a way to see, in one
> place, the stream of changes occurring in a project -- something which
> RCS could not do for you.

The only problem is that we need to have a Changelog for upstream, i.e.
Emacs.

> However, in this modern era of project-wide, atomic commits, the
> ChangeLog is not only an archaism, but is a continuous source of merge
> conflicts. For example, when I reverted Russell's latest change -- a
> one-liner that was minor in the extreme -- I had to do with a merge
> conflict in lisp/ChangeLog.

If the real problem you're trying to solve is the merge conflicts you
get with the Changelog files then the solution might be Bruno Haible’s
git merge driver for GNU-style ChangeLog files[1] (available in gnulib[2]).

Automatic generation of the Changelog file sounds like a fine solution
and I'm all for it, but when it comes down to the actual requirements of
the Changelog (such as file and especially function names) things don't
look that rosy anymore (doesn't work outside of Emacs, can no longer use
M-x add-change-log-entry, etc).

So before pouring out the baby with the bathwater maybe we should at
least try if the git merge driver solves the main problem we have with
the Changelog files.  

Thanks
Christian

Footnotes: 
[1]  http://www.mail-archive.com/bug-gnulib@gnu.org/msg09183.html
[2]  http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c

-- 
Christian Egli
Swiss Library for the Blind, Visually Impaired and Print Disabled
Grubenstrasse 12, CH-8045 Zürich, Switzerland

Re: Re: A request: Moving away from ChangeLog

[Julien Danjou]

[-- Attachment #1.1: Type: text/plain, Size: 936 bytes --]

On Fri, May 21 2010, Christian Egli wrote:

> So before pouring out the baby with the bathwater maybe we should at
> least try if the git merge driver solves the main problem we have with
> the Changelog files.  

This does not resolve a ugly part which is the duplication of
information: in the changelog file and in the commit changelog.

Documenting commit properly should be enough.

A better idea, if you want a user readable changelog, is 2 write the
commit message in a parseable format with 2 information: one for the
developer (what the commit changes in the code, API, whatever), and one
for the user (what it changes in the software usage). That last one only
if necessary.

And with this, it's a win-win: you can generate changelog files, and you
can read changelog while reading commit/bisecting/whatever git action
you do.

-- 
Julien Danjou
// ᐰ <julien@danjou.info>   http://julien.danjou.info

[-- Attachment #1.2: Type: application/pgp-signature, Size: 197 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: A request: Moving away from ChangeLog

[Carsten Dominik]

Hi Christian,

are we ready to install org-taskjuggler.el into Org-mode?
Where do you want it, core or contrib?

I did not yet hear from you that the FSF assignment process
is done, could you please update me on that?

Thanks.

- Carsten

On May 21, 2010, at 11:10 PM, Christian Egli wrote:

> Hi all
>
> John Wiegley <jwiegley@gmail.com> writes:
>
>> The Emacs ChangeLog is a file which predates the existence of freely
>> available, project-wide version control. It was a way to see, in one
>> place, the stream of changes occurring in a project -- something  
>> which
>> RCS could not do for you.
>
> The only problem is that we need to have a Changelog for upstream,  
> i.e.
> Emacs.
>
>> However, in this modern era of project-wide, atomic commits, the
>> ChangeLog is not only an archaism, but is a continuous source of  
>> merge
>> conflicts. For example, when I reverted Russell's latest change -- a
>> one-liner that was minor in the extreme -- I had to do with a merge
>> conflict in lisp/ChangeLog.
>
> If the real problem you're trying to solve is the merge conflicts you
> get with the Changelog files then the solution might be Bruno Haible’s
> git merge driver for GNU-style ChangeLog files[1] (available in  
> gnulib[2]).
>
> Automatic generation of the Changelog file sounds like a fine solution
> and I'm all for it, but when it comes down to the actual  
> requirements of
> the Changelog (such as file and especially function names) things  
> don't
> look that rosy anymore (doesn't work outside of Emacs, can no longer  
> use
> M-x add-change-log-entry, etc).
>
> So before pouring out the baby with the bathwater maybe we should at
> least try if the git merge driver solves the main problem we have with
> the Changelog files.
>
> Thanks
> Christian
>
> Footnotes:
> [1]  http://www.mail-archive.com/bug-gnulib@gnu.org/msg09183.html
> [2]  http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
>
> -- 
> Christian Egli
> Swiss Library for the Blind, Visually Impaired and Print Disabled
> Grubenstrasse 12, CH-8045 Zürich, Switzerland
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten

Re: Re: A request: Moving away from ChangeLog

[Christian Egli]

Hi Carsten

Carsten Dominik <carsten.dominik@gmail.com> writes:

> are we ready to install org-taskjuggler.el into Org-mode?

I modified it so that it no longer uses the ID property, so from that
perspective it should be ready. What is missing is a little section for
the manual and the integration in the the exporter and the build system.

> Where do you want it, core or contrib?

I would want to add it to the core.

> I did not yet hear from you that the FSF assignment process
> is done, could you please update me on that?

I just today got an email from FSF saying that my assignment/disclaimer
process (for all of GNU Emacs) with the FSF is complete. If you like I
can send you copies of the signed PDFs.

Should I push to a branch (e.g. taskjuggler-export) on repo.or.cz and
take it from there?

Thanks
Christian
-- 
Christian Egli
Swiss Library for the Blind, Visually Impaired and Print Disabled
Grubenstrasse 12, CH-8045 Zürich, Switzerland

Re: Re: A request: Moving away from ChangeLog

[Carsten Dominik]

On Jun 2, 2010, at 9:44 AM, Christian Egli wrote:

> Hi Carsten
>
> Carsten Dominik <carsten.dominik@gmail.com> writes:
>
>> are we ready to install org-taskjuggler.el into Org-mode?
>
> I modified it so that it no longer uses the ID property, so from that
> perspective it should be ready. What is missing is a little section  
> for
> the manual and the integration in the the exporter and the build  
> system.

You do have a tutorial on Worg, so I guess a small section would  
suffice?
Please go ahead and write it.

>
>> Where do you want it, core or contrib?
>
> I would want to add it to the core.
>
>> I did not yet hear from you that the FSF assignment process
>> is done, could you please update me on that?
>
> I just today got an email from FSF saying that my assignment/ 
> disclaimer
> process (for all of GNU Emacs) with the FSF is complete. If you like I
> can send you copies of the signed PDFs.

Excellent.

>
> Should I push to a branch (e.g. taskjuggler-export) on repo.or.cz and
> take it from there?

Maybe first write the manual section, then update your branch
to the current master, and then push it and tell me about
it - I will then merge the branch.

Thanks!

- Carsten