[RFC] Policy change for ChangeLog

classic Classic list List threaded Threaded
33 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
Quoting Chris Shoemaker <[hidden email]>:

> On Fri, Dec 02, 2005 at 04:10:24PM -0500, Derek Atkins wrote:
>> I would prefer if you refrained at this moment..  I don't think we have
>> consensus on this change, yet.
>
> Sorry, I pulled the trigger just before I saw your mail.  There does
> seem to be support for *some* change.  My change doesn't affect
> anything immediately, but it'll give people something to critique.

Yea, it creates ChangeLog.svn; it doesn't overwrite ChangeLog..
So yea, we can critique it..

> -chris

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Neil Williams-2
In reply to this post by Derek Atkins
On Friday 02 December 2005 8:59 pm, Derek Atkins wrote:
> I just thought of the one reason this proposal really bothers me.
> I knew there was something that wasn't sitting right and why I didn't
> think this would work.  It's not that I'm against making developers
> lives easier, but I want to make sure we don't lose something in kind.
>
> I like the ability to specify what changed in each and every file.

Sometimes, yes, especially if the commit fixes a couple of different issues
across different (but interdependent) files. However, recently I've found
this does generate duplication. There have been quite a few ChangeLog entries
that are:
        * various :
or
        Change description
        * src/path/somefile :
        * src/foo/bar.c :

where one change affects all listed files almost equally. The FSF address
change is the clearest example but it happens more often than that.

What I'd like is that the ChangeLog entries become "recommended" but not
"mandatory".

Just getting rid of the warning about reverting any changes that lack a
ChangeLog entry would be a welcome step.

Let those changes that need file-level detail go into the ChangeLog and those
changes that really are one change across multiple files can be left to the
svn commit messages, or an over-arching comment in NEWS, README or whichever
file is the most suitable.

> When you leave the ChangeLog generation out of the developer's hands,
> you can't get this level of detail.  All you get is the overarching
> description.  You lose the ability to say what happened in each file.
> Maybe you don't document your changes enough to want that ability,
> but I do.

Usually I do, but not always.

I'm thinking of all those changes to the header files replacing private
headers or removing unnecessary headers. The ChangeLog entries for a lot of
those are just bloat - and because of the ChangeLog format of short lines,
not using line wrapping, each section takes up a lot of lines.

> Personally I feel you should always run an "svn diff | more" prior
> to the commit to make sure you're only committing the change(s) you
> want.

(Can't think why, but my diff's tend to be so large I need to redirect it to a
file!)
:-)

> Then C-x C-s the ChangeLog buffer,
> M-w to copy the changelog entry, and then C-y once you get the svn commit

And in English for those who don't speak emacs ?!?!!
:-)

--

Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

attachment0 (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
In reply to this post by Chris Shoemaker
Quoting Chris Shoemaker <[hidden email]>:

>> When you leave the ChangeLog generation out of the developer's hands,
>> you can't get this level of detail.
>
> Sure you can.  Just include those details in the commit message.

But then the actual ChangeLog looks... Weird.  Or at least I suspect
it would.  I'd have to take a look and see for sure.

>> Personally I feel you should always run an "svn diff | more" prior
>> to the commit to make sure you're only committing the change(s) you
>> want.  Note that unlike cvs, an svn diff does not touch the network.
>> Indeed, you could even create your ChangeLog entry as you're perusing
>> your svn diff prior to commit..  Then C-x C-s the ChangeLog buffer,
>> M-w to copy the changelog entry, and then C-y once you get the svn commit
>> log buffer.  Then just type what you want for the email subject in
>> the top line of the buffer and you're done.
>
> Ok, yeah, that's pretty much the process I envisioned.  When you write
> it out like that it seems even more circular.  Svn knows what files we
> changed, so we:
>  1) ask it what we changed,
>  2) cut-n-paste file list into ChangeLog,
>  3) describe our commit,
>  4) cut-n-paste back into svn when it asks why we're
> changing the files.
>
> I'm sure I'll be glad when I can skip 1, 2 and 4.  And for the poor
> souls who aren't using emacs... :(

I'll skip the religious question of why you aren't using emacs...  (But I
think that if you were a lot of your issues would just go away)..  However,
I will say that you CANNOT and SHOULD NOT skip step 1.  You should ALWAYS
ALWAYS ALWAYS run a "svn diff" prior to commit to audit your own changes.

I admit that steps 2 and 4 may seem superfluous, but with the right tools
it takes zero time.  You're the one who keeps talking about using the
right tools for the job.  I maintain "emacs" is a good one :)

> -chris

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Neil Williams-2
In reply to this post by Chris Shoemaker
On Friday 02 December 2005 9:32 pm, Chris Shoemaker wrote:
> > All you get is the overarching description.  You lose the ability to
> > say what happened in each file.  Maybe you don't document your
> > changes enough to want that ability, but I do.
>
> Per-file documentation of a single commit is fine.  Documenting the
> same commit in two different places (potentially inconsistently) is
> the problem.

David's last commit is a case in point. Just what is the benefit of the
ChangeLog entry compared to the email to gnucash-changes?

Modified:
   gnucash/trunk/ChangeLog
   gnucash/trunk/src/business/business-gnome/dialog-date-close.c
   gnucash/trunk/src/gnome-search/dialog-search.c
   gnucash/trunk/src/gnome-search/search-account.c
   gnucash/trunk/src/gnome-utils/dialog-options.c
   gnucash/trunk/src/gnome-utils/gnc-date-edit.c
   gnucash/trunk/src/gnome-utils/gnc-html-graph-gog.c
   gnucash/trunk/src/gnome/dialog-sxsincelast.c
   gnucash/trunk/src/gnome/dialog-tax-info.c
   gnucash/trunk/src/gnome/window-reconcile.c
   gnucash/trunk/src/register/register-gnome/gnucash-header.c
Log:
Eliminate the deprecated function gtk_widget_set_usize().


Modified: gnucash/trunk/ChangeLog
===================================================================
--- gnucash/trunk/ChangeLog     2005-12-01 01:14:03 UTC (rev 12075)
+++ gnucash/trunk/ChangeLog     2005-12-01 01:45:24 UTC (rev 12076)
@@ -1,5 +1,17 @@
 2005-11-30  David Hampton  <[hidden email]>
 
+       * src/register/register-gnome/gnucash-header.c:
+       * src/business/business-gnome/dialog-date-close.c:
+       * src/gnome-utils/gnc-date-edit.c:
+       * src/gnome-utils/gnc-html-graph-gog.c:
+       * src/gnome-utils/dialog-options.c:
+       * src/gnome/window-reconcile.c:
+       * src/gnome/dialog-sxsincelast.c:
+       * src/gnome/dialog-tax-info.c:
+       * src/gnome-search/search-account.c:
+       * src/gnome-search/dialog-search.c: Eliminate the deprecated
+       function gtk_widget_set_usize().

That is just bloat. No?

That's no disrespect to you, David, just an illustration of the duplication
inherent in the current methods.

If we want this info in the ChangeLog for those who work on the distribution
tarball, then do we need the ChangeLog diff sent to the gnucash-changes
mailing list?

Can we exempt ChangeLog from the gnucash-changes content?
(Looking at the duplication from the other direction.)

> Ok, yeah, that's pretty much the process I envisioned.  When you write
> it out like that it seems even more circular.  Svn knows what files we
> changed, so we:
>   1) ask it what we changed,
>   2) cut-n-paste file list into ChangeLog,
>   3) describe our commit,
>   4) cut-n-paste back into svn when it asks why we're
> changing the files.
>
> I'm sure I'll be glad when I can skip 1, 2 and 4.  And for the poor
> souls who aren't using emacs... :(
OK. My process, not using emacs:

1. Ask svn status what has been changed and make sure any svn move operations
show up (!)
2. Direct svn diff to a file and inspect.
3. Copy svn status output into the ChangeLog using vi.
4. Edit the ChangeLog to describe each part of the upcoming commit.
(no network access yet)
5. Make the commit using -m to add a short commit message.

I'd like the *option* to skip stages 3 and 4 if the changes are repetitively
making the same changes to multiple files or unrelated to the final
distributed code.

I think this is particularly important for Doxygen fixes.

I cannot see how maintainers benefit from all the bloat arising from
documenting all the Doxygen tweaks in ChangeLog.

Can we recommend that ChangeLog is only for CODE changes and that changes to
comments, AUTHORS, README, Doxygen, things like the FSF address change and
housekeeping tasks like removing unwanted headers are simply not put into
ChangeLog at all?

Basically, keep ChangeLog for changes that actually change the compiled
binaries or build system?

--

Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

attachment0 (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Bugzilla from bock@step.polymtl.ca
In reply to this post by Neil Williams-2
On December 2, 2005 04:45 pm, Neil Williams wrote:

> Sometimes, yes, especially if the commit fixes a couple of different issues
> across different (but interdependent) files. However, recently I've found
> this does generate duplication. There have been quite a few ChangeLog
> entries that are:
>         * various :
> or
>         Change description
>         * src/path/somefile :
>         * src/foo/bar.c :
>
> where one change affects all listed files almost equally. The FSF address
> change is the clearest example but it happens more often than that.
>
> What I'd like is that the ChangeLog entries become "recommended" but not
> "mandatory".
>
> Just getting rid of the warning about reverting any changes that lack a
> ChangeLog entry would be a welcome step.
>
> Let those changes that need file-level detail go into the ChangeLog and
> those changes that really are one change across multiple files can be left
> to the svn commit messages, or an over-arching comment in NEWS, README or
> whichever file is the most suitable.
I disagree, that would be terrible.  There must be one place where all the
change can be reviewed in chronological orded.  I don't really care that's
it's generated or not (I prefer it to be generated from the svn logs
however), but one way or another that definitive list of changes should
exist.  

I do agree that having file level entries should be left to the good judgement
of the developer, since it's sometimes just impossible or undesireable to be
exhaustive anyway.  But all commits should have some log entry (even if it's
just "Fix typos"), just so one knows if it's a trivial change or a forgotten
log.

I think the easiest would be to keep writing Changelog entries like we used to
do, not be too strict about file lists, but only put them in the svn log
message.
--
Benoit Grégoire, http://benoitg.coeus.ca/

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

attachment0 (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
In reply to this post by Derek Atkins
On Fri, Dec 02, 2005 at 04:50:22PM -0500, Derek Atkins wrote:
> Quoting Chris Shoemaker <[hidden email]>:
>
> >>When you leave the ChangeLog generation out of the developer's hands,
> >>you can't get this level of detail.
> >
> >Sure you can.  Just include those details in the commit message.
>
> But then the actual ChangeLog looks... Weird.  Or at least I suspect
> it would.  I'd have to take a look and see for sure.

It might look weird if you feel compelled to format the file list in
the way designed to communicate as much as possible about the
file.  But, once the committer gets use to the idea that svn is
keeping track of recording and reporting all the details like full
pathname and branch, he is freed up to use the format most appropriate
for making the point at hand.  That format may not be:

        * path/to/file/one/foo.c: explanation
        * anotherpath/to/anotherfile/two/bar.c: more explanations
        etc...

but maybe more like: "files in one/ now use the new functions provided
in two/"

> >I'm sure I'll be glad when I can skip 1, 2 and 4.  And for the poor
> >souls who aren't using emacs... :(
>
> I admit that steps 2 and 4 may seem superfluous, but with the right tools
> it takes zero time.  You're the one who keeps talking about using the
> right tools for the job.  

That *does* sound like something I'd say.  :)

> I maintain "emacs" is a good one :)

Just to clarify: I *do* use emacs, and I agree.  *All* of the gnucash
development I've done has been in emacs, and probably will be.  But,
I'm concerned not to allow my use of a tool that efficiently
compensates for a poor process to prevent me from improving that
process for the benefit of those who use less sophisticated tools.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Lyttle
In reply to this post by Christian Stimming
On Fri, 2005-12-02 at 15:45 +0100, Christian Stimming wrote:

> Derek Atkins schrieb:
> >> On Thu, 2005-12-01 at 16:25 -0500, Chris Shoemaker wrote:
> >>
> >>> Comments?
> >>
> >> This change is fine with me, and sounds good.
> >
> > Before we go ahead with this, I'd like to hear from Chris Lyttle
> > and Christian Stimming..  They're the ones who usually use the
> > ChangeLog to generate the NEWS and release notes.  I'd like to
> > hear if they are willing to accept the new process going forward.
>
> I wouldn't throw away our ChangeLog convention too quickly. It used to
> be (and still is) a good compromise between readability and verbosity.
>
> The problem is that we don't have any experience with maintaining that
> obnoxious "big picture file", which supposedly would be the NEWS file.
> So far that file has been used for the release notes until 1.7.8 but is
> unused since them. We do have experience with the Changelog file, and
> these are good experiences so far. Developer tend to copy the ChangeLog
> entry to the CVS/SVN commit log or vice versa, so this convention
> doesn't seem to put too much of an additional work on the developers.

Um, actually even tho HEAD currently doesn't have the NEWS file from
1.8.x it is there and NEWS has been updated for every release so far. I
know, I do those updates 'manually' from looking at the log messages in
the Changelog and watering it down for public consumption. The 1.8.x
NEWS file should probably be merged back over to HEAD.

>
> As for compiling the release notes: Definitely the "svn log" is way too
> verbose for the normal release note compilation. Currently working
> through anything between 100 or 500 lines of ChangeLog during 1.8.x was
> doable, but thousands of lines of "svn log" really is way too much.
>
> IMHO our ChangeLog convention or what developers did from that meant
> that all the totally-trivial things were already filtered out, and this
> would be lost if we don't use ChangeLog at all. The point is that
> ChangeLog still is the "note collection for the developers", whereas the
> NEWS is the "note collection for the public", i.e. only that stuff that
> as the time of writing is already considered fundamentally important.
> Many things that might not be considered important at the time of
> writing will not be added to the NEWS file, whereas they are added to
> the ChangeLog -- where the release note collectors will pick it up at
> the time when it's required.
>
> > At some level it's OUR job as developers to make OTHERS lives
> > easier..  While we should certainly use tools to make OUR lives
> > easier, we need to think of who is using what we create and how
> > they use it.  Making life easier for us at their expense is NOT
> > okay.  So, I'd like to hear from wilddev and cstim first.
>
> I prefer if there still is a place where every developer adds a note for
> the majority of the non-trivial commits. Doesn't have to be the
> ChangeLog, but IMHO that's the easiest way to do this. The NEWS file
> IMHO is "too official"/"too public" for that goal.
>

I agree with the idea of only doing a ChangeLog for each major release.
It is necessary to be able to look back over how the current release is
developed IMHO. I really would not like to see a ChangeLog file
auto-generated from commit messages. I've seen far to many of those go
by with 'updated blah for foobar' which really doesn't give me enough to
write the NEWS file with. The ChangeLog nearly always has that sort of
info. Anyway, since I started doing this I thought the point of the
ChangeLog was to relay why the dev's were changing things to the public
who might be interested in that info. I know I quite often look into a
tarball's ChangeLog to figure out what files have changed in a new
release of something or to see if a bug I filed was actually fixed. So I
guess my point here is ChangeLog isn't only for dev's even tho they
mainly update it.

Chris
--
RedHat Certified Engineer #807302549405490.
Checkpoint Certified Security Expert 2000 & NG
--------------------------------------------
        |^|
        | |   |^|
        | |^| | |  Life out here is raw
        | | |^| |  But we will never stop
        | |_|_| |  We will never quit
        | / __> |  cause we are Metallica
        |/ /    |
        \       /
         |     |
--------------------------------------------

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
On Fri, Dec 02, 2005 at 06:37:32PM -0700, Chris Lyttle wrote:
> Um, actually even tho HEAD currently doesn't have the NEWS file from
> 1.8.x it is there and NEWS has been updated for every release so far. I
> know, I do those updates 'manually' from looking at the log messages in
> the Changelog and watering it down for public consumption. The 1.8.x
> NEWS file should probably be merged back over to HEAD.

Strange.  It's on the 1.8 branch.  I wonder how much other stuff is
sitting in 1.8 that should be in HEAD...

> I agree with the idea of only doing a ChangeLog for each major release.
> It is necessary to be able to look back over how the current release is
> developed IMHO. I really would not like to see a ChangeLog file
> auto-generated from commit messages. I've seen far to many of those go
> by with 'updated blah for foobar' which really doesn't give me enough to
> write the NEWS file with. The ChangeLog nearly always has that sort of
> info.

I also noticed that sometimes the commit messages aren't as helpful as
the ChangeLog entries.  But, I'm not suggesting we should stop writing
good commit descriptions, just that we should only manually put good
commit descriptions into just one place.  So, a ChangeLog exported
from svn should be just as informative (if not more) for harvesting
NEWS entries.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Thomas Bushnell BSG
In reply to this post by Chris Shoemaker
Chris Shoemaker <[hidden email]> writes:

> I don't think this little detail is correct.  A ChangeLog also does
> not satisfy that requirement.  
>
> GPL 2a) "You must cause the modified files to carry prominent notices
> stating that you changed the files and the date of any change."

This is technically true, but the point is of course the *substance*
of the requirement.

Distributing a ChangeLog at least meets the substance of the
requirement, if it has a technical inadequacy.  Distributing *nothing*
is clearly wrong.

> It becomes very clear that the ChangeLog is insufficient when we
> realize that the GPL must be followed in whatever GPL'd work we
> *distribute*.  We are currently distributing the individual GPL'd
> files via several public methods.  Yes, the individual files are GPL'd
> works; they say so explicitly.

The GPL applies to the program as a whole, not to individual files.
It does not matter that people can down load the files one at a time
if they wish.

> There is clearly some room for improvement of the GPL here.

I think there is general agreement that 2a is problematic, and at one
point, back when I worked for the FSF, it was a low priority back
burner issue for some future GPL improvement.
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
In reply to this post by Neil Williams-2
Neil Williams <[hidden email]> writes:

> On Friday 02 December 2005 9:32 pm, Chris Shoemaker wrote:
>> > All you get is the overarching description.  You lose the ability to
>> > say what happened in each file.  Maybe you don't document your
>> > changes enough to want that ability, but I do.
>>
>> Per-file documentation of a single commit is fine.  Documenting the
>> same commit in two different places (potentially inconsistently) is
>> the problem.
>
> David's last commit is a case in point. Just what is the benefit of the
> ChangeLog entry compared to the email to gnucash-changes?

Email is empheral, and it's not distributed with the tarball.
The ChangeLog is saved and is part of the tarball.  The benefit
is distributed a log of the changes in the tarball, which /is/
the end goal.

[snip]

> That is just bloat. No?

I don't consider it bloat.

> That's no disrespect to you, David, just an illustration of the duplication
> inherent in the current methods.

Um, no, that's not the duplication that Chris is complaining about.
He's not complaining about the gnucash-changes email -- he's
complaining about the work required to actually modify the changelog
and then cut-and-paste that into the commit log.

> Can we exempt ChangeLog from the gnucash-changes content?
> (Looking at the duplication from the other direction.)

I don't think so.  You're welcome to look at the email hook and
suggest a patch...  But I really don't see why.  IMHO working on that
is just a waste of your time.

> OK. My process, not using emacs:
>
> 1. Ask svn status what has been changed and make sure any svn move operations
> show up (!)
> 2. Direct svn diff to a file and inspect.
> 3. Copy svn status output into the ChangeLog using vi.
> 4. Edit the ChangeLog to describe each part of the upcoming commit.
> (no network access yet)
> 5. Make the commit using -m to add a short commit message.
>
> I'd like the *option* to skip stages 3 and 4 if the changes are repetitively
> making the same changes to multiple files or unrelated to the final
> distributed code.

I /do/ think it's reasonable for a repetative commit to eliminate
the list of files changed from the ChangeLog.  However you should
still make a ChangeLog entry.  E.g.:

   1000-13-32    Joe Q. Developer <[hidden email]>

          * corrected the FSF address in every source file

IMHO a ChangeLog entry like this is /perfectly reasonable/.

> I think this is particularly important for Doxygen fixes.
>
> I cannot see how maintainers benefit from all the bloat arising from
> documenting all the Doxygen tweaks in ChangeLog.

It gives a history of when a file was changed and how.

> Can we recommend that ChangeLog is only for CODE changes and that changes to
> comments, AUTHORS, README, Doxygen, things like the FSF address change and
> housekeeping tasks like removing unwanted headers are simply not put into
> ChangeLog at all?

Nah.  I'd like a log of all changes, please.

> Basically, keep ChangeLog for changes that actually change the compiled
> binaries or build system?

Why?  Is it really that much /work/ to create a ChangeLog entry?
The 'bloat' as you call it is unimportant.  Size can be handled
fine.  We have plenty of space.  Disk is cheap.

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
In reply to this post by Neil Williams-2
Neil Williams <[hidden email]> writes:

> What I'd like is that the ChangeLog entries become "recommended" but not
> "mandatory".
>
> Just getting rid of the warning about reverting any changes that lack a
> ChangeLog entry would be a welcome step.

You're taking the 'warning' way too literally.  The idea is to keep a
log (NOT in the SCM metadata) of changes made to GnuCash.  When was
the last time a change was reverted because it lacked a ChangeLog
entry?

Now, don't let this mean you're welcome to stop making ChangeLog
entries.  See my previous email about that.  I think it's perfectly
reasonable in certain cases (in particular cases where you're not
changing real code) to /not/ enumerate the changed files in the
ChangeLog.  BUT...  I think you still MUST make a log entry!

>> Personally I feel you should always run an "svn diff | more" prior
>> to the commit to make sure you're only committing the change(s) you
>> want.
>
> (Can't think why, but my diff's tend to be so large I need to redirect it to a
> file!)
> :-)

Okay, if you're going to be pedantic, personally I feel you should
always run "svn diff" and audit the output using whatever method you
prefer, but you should ALWAYS audit the "svn diff" before you commit.
Better?   :-P

>> Then C-x C-s the ChangeLog buffer,
>> M-w to copy the changelog entry, and then C-y once you get the svn commit
>
> And in English for those who don't speak emacs ?!?!!

"The [Save] the ChangeLog buffer, [copy-to-cut-buffer] to copy the
changelog entry, and then [yank-from-cut-buffer] once you get the
svn commit"

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
In reply to this post by Chris Shoemaker
Chris Shoemaker <[hidden email]> writes:

> I also noticed that sometimes the commit messages aren't as helpful as
> the ChangeLog entries.  But, I'm not suggesting we should stop writing
> good commit descriptions, just that we should only manually put good
> commit descriptions into just one place.  So, a ChangeLog exported
>>From svn should be just as informative (if not more) for harvesting
> NEWS entries.

See, I see it the other way around.  Write a good ChangeLog entry
and then copy it to the svn commit.  Then you're guaranteed a good
log.  :)

It's REALLY not a lot of work, Chris.  We've spent an order of
magnitude more time arguing about it than just cut-and-pasting
the changelog into the svn commit every time.

I just don't understand why you feel like micro-optimizing things?
Does it really take that much time to do this?  Aren't there other,
larger issues that should be handled first?

-derek
--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Karl Hegbloom
In reply to this post by Derek Atkins
I was taught to maintain ChangeLog as I edit.  In Emacs, you type:

  C-x 4 a

... to add a ChangeLog entry.  (Will a vim user please explain the
process used?  Does it automatically insert a ChangeLog entry template
with the ISO-8601 date, file name, and function?)  So for each change
you make, you make a note of it, as you go, so that later on, when you
review the diff prior to commit, you have less work to do, and you won't
have forgotten why you did something.  It takes a certain amount of
discipline to do this, but make it easier not to forget to make an
entry.

With pcl-cvs, it would take the ChangeLog and pull out the pieces
pertaining to a set of files you are committing, to use for the commit
log entry.  The psvn interface should do that also, if it doesn't
already.  Again, I'm not a vim user, so someone familiar with that would
have to explain the process.  Do you use an external tool for working
with svn?  A Perl script could pull the ChangeLog parts out into a
commit log you can edit prior to commit...

Earlier, someone mentioned using ChangeLog for listing things like
what's changed in the API, new features, deprecations, etc., but that's
not what ChangeLog is for.  That's what NEWS is for.

IMO, trying to make an automatically generated ChangeLog from svn commit
log entries is inviting laziness wrt writing readable and meaningful log
entries that mention every significant modification.  You are not
supposed to commit after every little change as you go.  You are
supposed to get it all squared away, then commit a related set of
changes as a unit.  Sometimes it takes several days of work to get that
all together, and so logging as you go becomes more important.  It
prevents you from forgetting to log a change.  Reviewing a pile of diffs
to see what you changed so you can write a log entry is tedious.  If the
changes are already logged, then the review of the diff is just a quick
scan --- you don't have to totally parse every modification then.

--
Karl Hegbloom <[hidden email]>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
12