Re: [changeset] don't remove whitespace within @example in docstrings

classic Classic list List threaded Threaded
42 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Re: [changeset] don't remove whitespace within @example in docstrings

Benjamin Lindner


[hidden email] wrote:

> On Fri, Nov 28, 2008 at 09:59:46PM +0100, Thorsten Meyer wrote:
>> Actually, perl seems to be available in the MSYS supplementary tools.
>> See here:
>> http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=67879.
>
> Yes, but it has to be installed.
>
>> Apart from that: is your concern only about availability of perl or
>> maybe also about adding risc of compatibility  issues in the build
>> process or general maintainability of the build process?
>
> My personal concern is that I always hesitate to add additional
> dependencies.. Note that I've added quite a few myself, but I always
> think first how I can do without them. If there is an easy way to do
> without that doesn't introduce too much code in Octave and is just as
> performant, then better in a general sense to go with the solution that
> doesn't add dependencies.
>
> Note in this case that Octave already has a dependency on Perl, which
> I'd though was used for octave.desktop. However, its not used for that,
> but rather to extract the error numbers and build the option handling
> code for things like dassl. So Octave in fact already has a pretty
> strong dependency on Perl.. So I withdraw my concern on additional
> dependencies..
>
> Regards
> D.
>

If the current supplied version of perl (5.6.1) with msys is sufficient,
I don't see a big problem requiring it to be installed when building
octave using msys/win32.

I'm not so certain that (future) new versions will be available quickly
for msys, so requiring them would pose some problem for building octave
on windows using msys.

benjamin
Reply | Threaded
Open this post in threaded view
|

Re: [changeset] don't remove whitespace within @example in docstrings

Thorsten Meyer


Benjamin Lindner wrote:

>
>
> [hidden email] wrote:
>> On Fri, Nov 28, 2008 at 09:59:46PM +0100, Thorsten Meyer wrote:
>>> Actually, perl seems to be available in the MSYS supplementary tools.
>>> See here:
>>> http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=67879.
>>>
>>
>> Yes, but it has to be installed.
>>
>>> Apart from that: is your concern only about availability of perl or
>>> maybe also about adding risc of compatibility  issues in the build
>>> process or general maintainability of the build process?
>>
>> My personal concern is that I always hesitate to add additional
>> dependencies.. Note that I've added quite a few myself, but I always
>> think first how I can do without them. If there is an easy way to do
>> without that doesn't introduce too much code in Octave and is just as
>> performant, then better in a general sense to go with the solution
>> that doesn't add dependencies.
>> Note in this case that Octave already has a dependency on Perl, which
>> I'd though was used for octave.desktop. However, its not used for
>> that, but rather to extract the error numbers and build the option
>> handling code for things like dassl. So Octave in fact already has a
>> pretty strong dependency on Perl.. So I withdraw my concern on
>> additional dependencies..
>>
>> Regards
>> D.
>>
>
> If the current supplied version of perl (5.6.1) with msys is
> sufficient, I don't see a big problem requiring it to be installed
> when building octave using msys/win32.
>
> I'm not so certain that (future) new versions will be available
> quickly for msys, so requiring them would pose some problem for
> building octave on windows using msys.
For what is needed in the above patch, 5.6.1 is certainly sufficient.

regards

Thorsten
Reply | Threaded
Open this post in threaded view
|

Re: [changeset] don't remove whitespace within @example in docstrings

Jaroslav Hajek-2
In reply to this post by Benjamin Lindner
On Sat, Nov 8, 2008 at 10:46 AM, Thorsten Meyer <[hidden email]> wrote:

> Thorsten Meyer wrote:
>> Hi,
>>
>> during the build process of octave, the documentation strings within the .m files are extracted by
>> the script scripts/mkdoc. This scripts also removes white space before @-commands at the beginning
>> of lines. The script also removes white space before @result{}, which distorts the display of the
>> @examples in the documentations strings.
>>
>> Included, you will find a changeset that fixes mkdoc, such that it no longer eats white space
>> within @example environments.
> Oops, I forgot the attachement. Here it is. And thanks for the hint, Shai.
>
> Thorsten
>

Applied.
thanks

--
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz
Reply | Threaded
Open this post in threaded view
|

ChangeLogs (was: Re: [changeset] don't remove whitespace within @example in docstrings)

John W. Eaton
Administrator
On  5-Jan-2009, Jaroslav Hajek wrote:

| Applied.

Thanks for applying this change.

It still seems confusing to me that you leave the ChangeLog entry
alone when applying patches.  If I do "hg log" now, I see

  changeset:   8444:c3ac9f2772cd
  tag:         tip
  user:        Thorsten Meyer <[hidden email]>
  date:        Mon Jan 05 10:54:22 2009 +0100
  summary:     do not eat white space within @example environments of docstrings

at the top, but the ChangeLog entry for this change does not have a
Jan 5 date.  Instead, it has a 2008-11-07 date.  If I were looking at
this ChangeLog entry and wanted to find the corresponding changeset,
the date for the ChangeLog entry would not help me find the changeset.
This is why I think we should revise the date of the ChangeLog entry
when checking in changes so that new ChangeLog entries should always
appear at the top of the ChangeLog file.

Or, we should simply decide to do away with ChangeLog files entirely.
But if we do that, I think we should put much more complete commit
messages in the mercurial log files, and we should agree on a common
style for the commit messages.

jwe
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs (was: Re: [changeset] don't remove whitespace within @example in docstrings)

Jordi Gutiérrez Hermoso
2009/1/5 John W. Eaton <[hidden email]>:
> Or, we should simply decide to do away with ChangeLog files entirely.

Please don't... I like the Changelogs, since they're the only unbroken
breadcrumb trail we have for Octave. If in a couple of years from now
you decide that hg isn't doing the job anymore like CVS wasn't, then
we'd lose the project's history when you switch VCS.

It's a pity that Changelogs are human-generated instead of
machine-generated, since that introduces some human error... of course
Emacs, has a Changelog mode. :-) Do other editors have similar modes
too?

- Jordi G. H.
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs (was: Re: [changeset] don't remove whitespace within @example in docstrings)

Thomas Weber-8
On Mon, Jan 05, 2009 at 11:23:23AM -0600, Jordi Gutiérrez Hermoso wrote:
> 2009/1/5 John W. Eaton <[hidden email]>:
> > Or, we should simply decide to do away with ChangeLog files entirely.
>
> Please don't... I like the Changelogs, since they're the only unbroken
> breadcrumb trail we have for Octave. If in a couple of years from now
> you decide that hg isn't doing the job anymore like CVS wasn't, then
> we'd lose the project's history when you switch VCS.

You should have more trust in current conversion tools. I'm pretty sure
you can switch between at least Mercurial and Git without loosing
anything.

With distributed VCS, the importance of Changelogs has diminished.

> It's a pity that Changelogs are human-generated instead of
> machine-generated, since that introduces some human error... of course
> Emacs, has a Changelog mode. :-) Do other editors have similar modes
> too?

Generating changelogs with Mercurial isn't difficult, just try
        hg log --limit 2 --style=changelog
in Octave's directory. Adding something like this to 'make dist' hook
wouldn't be that much work.

        Thomas
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs (was: Re: [changeset] don't remove whitespace within @example in docstrings)

John W. Eaton
Administrator
On  5-Jan-2009, Thomas Weber wrote:

| On Mon, Jan 05, 2009 at 11:23:23AM -0600, Jordi Gutiérrez Hermoso wrote:
| > 2009/1/5 John W. Eaton <[hidden email]>:
| > > Or, we should simply decide to do away with ChangeLog files entirely.
| >
| > Please don't... I like the Changelogs, since they're the only unbroken
| > breadcrumb trail we have for Octave. If in a couple of years from now
| > you decide that hg isn't doing the job anymore like CVS wasn't, then
| > we'd lose the project's history when you switch VCS.
|
| You should have more trust in current conversion tools. I'm pretty sure
| you can switch between at least Mercurial and Git without loosing
| anything.

Yes, and I would expect that would be true of any widely used VCS
developed in the future as well.

| With distributed VCS, the importance of Changelogs has diminished.

Yes, I agree.

| Generating changelogs with Mercurial isn't difficult, just try
| hg log --limit 2 --style=changelog
| in Octave's directory. Adding something like this to 'make dist' hook
| wouldn't be that much work.

OK.  If we are to do this, then we should

  Only generate ChangeLog entries after the point when we stop editing
  them by hand.

  Agree on a format for the Mercurial log entries.  Future log entries
  should contain more information than they do now.

  Instead of having multiple ChangeLog files (top, doc, src,
  liboctave, libcruft, test, ...) There would only be one generated
  ChangeLog file that we would put in the tar files we distribute.

I don't see how the generated ChangeLog entries can have precisely the
format that we use now unless we edit it into the logs by hand anyway
(I'm thinking of the

        * file (function): Description.

format -- it doesn't seem that Mercurial could do that for us).  But
even without that, I'm OK with going this route once we decide on some
guidelines for the way Mercurial log entries should be written.

jwe

Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs (was: Re: [changeset] don't remove whitespace within @example in docstrings)

Jaroslav Hajek-2
In reply to this post by John W. Eaton
On Mon, Jan 5, 2009 at 5:32 PM, John W. Eaton <[hidden email]> wrote:

> On  5-Jan-2009, Jaroslav Hajek wrote:
>
> | Applied.
>
> Thanks for applying this change.
>
> It still seems confusing to me that you leave the ChangeLog entry
> alone when applying patches.  If I do "hg log" now, I see
>
>  changeset:   8444:c3ac9f2772cd
>  tag:         tip
>  user:        Thorsten Meyer <[hidden email]>
>  date:        Mon Jan 05 10:54:22 2009 +0100
>  summary:     do not eat white space within @example environments of docstrings
>
> at the top, but the ChangeLog entry for this change does not have a
> Jan 5 date.  Instead, it has a 2008-11-07 date.  If I were looking at
> this ChangeLog entry and wanted to find the corresponding changeset,
> the date for the ChangeLog entry would not help me find the changeset.
> This is why I think we should revise the date of the ChangeLog entry
> when checking in changes so that new ChangeLog entries should always
> appear at the top of the ChangeLog file.
>

Well, it depends on what you expect of this changelog entry. My
understanding is that this reflects the date when the patch was
created by its author; and, presumably, posted to the mailing list. It
can be applied much later by someone else (like in this case). That
later date is reflected by the date of the mercurial changeset.
When I transplant changesets to release archive, I use -D (which I had
to implement in Mercurial) to refresh the date. The date in ChangeLog
file still reflects the date of origin of the change.
What you would like to see in ChangeLogs, i.e. the date of
application, can be generated by running "hg annotate" on the
ChangeLog file and doing a little parsing of the result.

Another merit is purely practical - with the simple "changelogmask"
extension to mercurial I've created, treating changelog entries "my
way" makes most of patches apply cleanly (those that only prepend
lines to ChangeLog files). This was a real boost in the transplanting
process - prior to that, there was a conflict for almost every
transplanted patch; now, clean application is more common. I would be
unhappy to abandon this convenient practice :(

> Or, we should simply decide to do away with ChangeLog files entirely.
> But if we do that, I think we should put much more complete commit
> messages in the mercurial log files, and we should agree on a common
> style for the commit messages.
>

Another option, if you disagree with my treating of the dates, is to
simply left them out from the changelog files. After all, "your-style
dates" can be auto-generated.
But it will be probably good if we settle on a common style.

regards

--
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs (was: Re: [changeset] don't remove whitespace within @example in docstrings)

Jaroslav Hajek-2
In reply to this post by John W. Eaton
On Mon, Jan 5, 2009 at 5:32 PM, John W. Eaton <[hidden email]> wrote:

> On  5-Jan-2009, Jaroslav Hajek wrote:
>
> | Applied.
>
> Thanks for applying this change.
>
> It still seems confusing to me that you leave the ChangeLog entry
> alone when applying patches.  If I do "hg log" now, I see
>
>  changeset:   8444:c3ac9f2772cd
>  tag:         tip
>  user:        Thorsten Meyer <[hidden email]>
>  date:        Mon Jan 05 10:54:22 2009 +0100
>  summary:     do not eat white space within @example environments of docstrings
>
> at the top, but the ChangeLog entry for this change does not have a
> Jan 5 date.  Instead, it has a 2008-11-07 date.  If I were looking at
> this ChangeLog entry and wanted to find the corresponding changeset,
> the date for the ChangeLog entry would not help me find the changeset.
> This is why I think we should revise the date of the ChangeLog entry
> when checking in changes so that new ChangeLog entries should always
> appear at the top of the ChangeLog file.
>

Sorry, I didn't notice the changelog entry didn't go on top of the
file. I do agree that it always should. We should note this in
contrib.txi. Mea culpa.


> Or, we should simply decide to do away with ChangeLog files entirely.
> But if we do that, I think we should put much more complete commit
> messages in the mercurial log files, and we should agree on a common
> style for the commit messages.
>
> jwe
>



--
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

Thorsten Meyer
In reply to this post by John W. Eaton
John W. Eaton wrote:

> On  5-Jan-2009, Thomas Weber wrote:
>
> | On Mon, Jan 05, 2009 at 11:23:23AM -0600, Jordi Gutiérrez Hermoso wrote:
> | > 2009/1/5 John W. Eaton <[hidden email]>:
> | > > Or, we should simply decide to do away with ChangeLog files entirely.
> | >
> | > Please don't... I like the Changelogs, since they're the only unbroken
> | > breadcrumb trail we have for Octave. If in a couple of years from now
> | > you decide that hg isn't doing the job anymore like CVS wasn't, then
> | > we'd lose the project's history when you switch VCS.
> |
> | You should have more trust in current conversion tools. I'm pretty sure
> | you can switch between at least Mercurial and Git without loosing
> | anything.
>
> Yes, and I would expect that would be true of any widely used VCS
> developed in the future as well.
>
> | With distributed VCS, the importance of Changelogs has diminished.
>
> Yes, I agree.
>
> | Generating changelogs with Mercurial isn't difficult, just try
> | hg log --limit 2 --style=changelog
> | in Octave's directory. Adding something like this to 'make dist' hook
> | wouldn't be that much work.
>
> OK.  If we are to do this, then we should
>
>   Only generate ChangeLog entries after the point when we stop editing
>   them by hand.
>
>   Agree on a format for the Mercurial log entries.  Future log entries
>   should contain more information than they do now.
>
>   Instead of having multiple ChangeLog files (top, doc, src,
>   liboctave, libcruft, test, ...) There would only be one generated
>   ChangeLog file that we would put in the tar files we distribute.
>
> I don't see how the generated ChangeLog entries can have precisely the
> format that we use now unless we edit it into the logs by hand anyway
> (I'm thinking of the
>
> * file (function): Description.
>
> format -- it doesn't seem that Mercurial could do that for us).  But
> even without that, I'm OK with going this route once we decide on some
> guidelines for the way Mercurial log entries should be written.
>
Actually, I like the two level documentation that the current ChangeLog
+ commit message gives:
 - top level description and purpose of the changeset in the commit message
 - individual changes in the ChangeLog

Can this somehow be preserved with an automated ChangeLog (without
having to type the file names again)?

Here is an example of the output of hg log -style ChangeLog for a larger
patch:
2008-12-27  Jaroslav Hajek  <[hidden email]>

        * src/ChangeLog, src/oct-obj.cc, src/oct-obj.h, src/ov-base-diag.cc,
        src/ov-base-diag.h, src/ov-base-scalar.cc, src/ov-base.h, src/ov-
        bool-mat.cc, src/ov-bool-mat.h, src/ov-bool-sparse.cc, src/ov-bool-
        sparse.h, src/ov-bool.cc, src/ov-bool.h, src/ov-ch-mat.cc, src/ov-
        ch-mat.h, src/ov-colon.h, src/ov-complex.cc, src/ov-complex.h, src
        /ov-cx-mat.cc, src/ov-cx-mat.h, src/ov-cx-sparse.cc, src/ov-cx-
        sparse.h, src/ov-float.cc, src/ov-float.h, src/ov-flt-complex.cc,
        src/ov-flt-complex.h, src/ov-flt-cx-mat.cc, src/ov-flt-cx-mat.h, src
        /ov-flt-re-mat.cc, src/ov-flt-re-mat.h, src/ov-intx.h, src/ov-
        perm.cc, src/ov-perm.h, src/ov-range.h, src/ov-re-mat.cc, src/ov-re-
        mat.h, src/ov-re-sparse.cc, src/ov-re-sparse.h, src/ov-scalar.cc,
        src/ov-scalar.h, src/ov-str-mat.cc, src/ov-str-mat.h, src/ov.h:
        remove valid_as_scalar_index
        [f00578b495e9]

Now imagine this patch does 5 different kind of changes in 5 groups of
files to accomplish one major change. How should the ChangeLog look in
this case?
I think, it should still look like a list with 5 items for the 5 groups
of files. Is that possible with mercurial? For example, is it possible
to define a new style that will output (in ChangeLog format) only the
commit message  but not the list of files? Then we could simply write
into the commit message what we used to write into the ChangeLog files
preceded by another item, maybe like this:

purpose: fix a major bug
  * src/file1, src/file2: added this
  * scripts/file3, scripts/file4: removed that
  * doc/interpreter/file5: updated something else

regards

Thorsten
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

Daniel Sebald
In reply to this post by Jaroslav Hajek-2
Jaroslav Hajek wrote:

> On Mon, Jan 5, 2009 at 5:32 PM, John W. Eaton <[hidden email]> wrote:
>
>>On  5-Jan-2009, Jaroslav Hajek wrote:
>>
>>| Applied.
>>
>>Thanks for applying this change.
>>
>>It still seems confusing to me that you leave the ChangeLog entry
>>alone when applying patches.  If I do "hg log" now, I see
>>
>> changeset:   8444:c3ac9f2772cd
>> tag:         tip
>> user:        Thorsten Meyer <[hidden email]>
>> date:        Mon Jan 05 10:54:22 2009 +0100
>> summary:     do not eat white space within @example environments of docstrings
>>
>>at the top, but the ChangeLog entry for this change does not have a
>>Jan 5 date.  Instead, it has a 2008-11-07 date.  If I were looking at
>>this ChangeLog entry and wanted to find the corresponding changeset,
>>the date for the ChangeLog entry would not help me find the changeset.
>>This is why I think we should revise the date of the ChangeLog entry
>>when checking in changes so that new ChangeLog entries should always
>>appear at the top of the ChangeLog file.
>>
>
>
> Sorry, I didn't notice the changelog entry didn't go on top of the
> file. I do agree that it always should. We should note this in
> contrib.txi. Mea culpa.

This is the one disadvantage of putting ChangeLog hunks in the patch file.  They are almost always rejected because some other entry has already been placed at the top.  Anyone know of a command line switch to make diff force the hunk to be at the top when patched?

The patch date should be the date the patch was applied, not the date it was created, in my opinion.
 

>>Or, we should simply decide to do away with ChangeLog files entirely.
>>But if we do that, I think we should put much more complete commit
>>messages in the mercurial log files, and we should agree on a common
>>style for the commit messages.

A few nice things about ChangeLogs:

1) Legacy and consistency across projects.  I go from one bundled program to the next and see ChangeLog, INSTALL, README, and I almost immediately know what to do.

2) ChangeLog can be quickly grepped or searched.  Can source control log entries be searched as quickly?

3) Contributors who don't check in stuff can place a ChangeLog entry as a hunk in the patch file.

Dan
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

Jaroslav Hajek-2
On Tue, Jan 6, 2009 at 6:13 AM, Daniel J Sebald <[hidden email]> wrote:

> Jaroslav Hajek wrote:
>>
>> On Mon, Jan 5, 2009 at 5:32 PM, John W. Eaton <[hidden email]> wrote:
>>
>>> On  5-Jan-2009, Jaroslav Hajek wrote:
>>>
>>> | Applied.
>>>
>>> Thanks for applying this change.
>>>
>>> It still seems confusing to me that you leave the ChangeLog entry
>>> alone when applying patches.  If I do "hg log" now, I see
>>>
>>> changeset:   8444:c3ac9f2772cd
>>> tag:         tip
>>> user:        Thorsten Meyer <[hidden email]>
>>> date:        Mon Jan 05 10:54:22 2009 +0100
>>> summary:     do not eat white space within @example environments of
>>> docstrings
>>>
>>> at the top, but the ChangeLog entry for this change does not have a
>>> Jan 5 date.  Instead, it has a 2008-11-07 date.  If I were looking at
>>> this ChangeLog entry and wanted to find the corresponding changeset,
>>> the date for the ChangeLog entry would not help me find the changeset.
>>> This is why I think we should revise the date of the ChangeLog entry
>>> when checking in changes so that new ChangeLog entries should always
>>> appear at the top of the ChangeLog file.
>>>
>>
>>
>> Sorry, I didn't notice the changelog entry didn't go on top of the
>> file. I do agree that it always should. We should note this in
>> contrib.txi. Mea culpa.
>
> This is the one disadvantage of putting ChangeLog hunks in the patch file.
>  They are almost always rejected because some other entry has already been
> placed at the top.  Anyone know of a command line switch to make diff force
> the hunk to be at the top when patched?
>

No switch, AFAIK. But I've created a patch for Mercurial that accomplishes this
(or handles 99% cases): If a change to a ChangeLog file is detected that only
consists of prepended lines, the diff is done without context (so that
the hunk is
always prepended). Adjusting the date would be nontrivial, however.

> The patch date should be the date the patch was applied, not the date it was
> created, in my opinion.
>

Maybe, but that's way more complicated. Moreover, what if the patch is
transplanted
later to another repo? Should the date of the ChangeLog entries be updated?
Much more work.

>
>>> Or, we should simply decide to do away with ChangeLog files entirely.
>>> But if we do that, I think we should put much more complete commit
>>> messages in the mercurial log files, and we should agree on a common
>>> style for the commit messages.
>
> A few nice things about ChangeLogs:
>
> 1) Legacy and consistency across projects.  I go from one bundled program to
> the next and see ChangeLog, INSTALL, README, and I almost immediately know
> what to do.
>
> 2) ChangeLog can be quickly grepped or searched.  Can source control log
> entries be searched as quickly?
>

Sort of. It can be dumped and then searched.


> 3) Contributors who don't check in stuff can place a ChangeLog entry as a
> hunk in the patch file.
>

Well, you can place the changelog entry in a mercurial patch. Still,
there's one entry
per patch, not per directory, so that's a minor drawback.

> Dan
>



--
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

Daniel Sebald
Jaroslav Hajek wrote:
> On Tue, Jan 6, 2009 at 6:13 AM, Daniel J Sebald <[hidden email]> wrote:
[snip]

>>This is the one disadvantage of putting ChangeLog hunks in the patch file.
>> They are almost always rejected because some other entry has already been
>>placed at the top.  Anyone know of a command line switch to make diff force
>>the hunk to be at the top when patched?
>>
>
>
> No switch, AFAIK. But I've created a patch for Mercurial that accomplishes this
> (or handles 99% cases): If a change to a ChangeLog file is detected that only
> consists of prepended lines, the diff is done without context (so that
> the hunk is
> always prepended). Adjusting the date would be nontrivial, however.

Well, in that case Mercurial also records the date applied, I would think (hope).  I'm in ChangeLog frame of mind, hence reasoning as below:


>>The patch date should be the date the patch was applied, not the date it was
>>created, in my opinion.
>>
>
>
> Maybe, but that's way more complicated. Moreover, what if the patch is
> transplanted
> later to another repo? Should the date of the ChangeLog entries be updated?
> Much more work.

I'd have to think about that one.  But the advantage of organizing by date patched is that when one knows roughly when something stopped working s/he can quickly surmise what may have changed to cause the problem.


[snip]
>>3) Contributors who don't check in stuff can place a ChangeLog entry as a
>>hunk in the patch file.
>>
>
>
> Well, you can place the changelog entry in a mercurial patch. Still,
> there's one entry
> per patch, not per directory, so that's a minor drawback.

Good point.

Dan
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

John W. Eaton
Administrator
On  6-Jan-2009, Daniel J Sebald wrote:

| > Maybe, but that's way more complicated. Moreover, what if the patch is
| > transplanted
| > later to another repo? Should the date of the ChangeLog entries be updated?
| > Much more work.

If you are cloning an archive, then I don't think the dates should
change.  But if you are transplanting some changes from one branch to
another, then I think it might be useful for the dates to change.  I
think it depends on the purpose.

| I'd have to think about that one.  But the advantage of organizing
| by date patched is that when one knows roughly when something
| stopped working s/he can quickly surmise what may have changed to
| cause the problem.

Yes, that's a good reason for the ChangeLog entries to have the date
when the patch was applied.

I think we avoid these issues if we do away with hand-edited ChangeLog
files and simply generate them from the Mercurial archive when we make
releases.

jwe
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

Jaroslav Hajek-2
On Tue, Jan 6, 2009 at 1:19 PM, John W. Eaton <[hidden email]> wrote:

> On  6-Jan-2009, Daniel J Sebald wrote:
>
> | > Maybe, but that's way more complicated. Moreover, what if the patch is
> | > transplanted
> | > later to another repo? Should the date of the ChangeLog entries be updated?
> | > Much more work.
>
> If you are cloning an archive, then I don't think the dates should
> change.  But if you are transplanting some changes from one branch to
> another, then I think it might be useful for the dates to change.  I
> think it depends on the purpose.
>

Now that's an idea I really don't like (because of the amount of
manual editing it brings).
In that case, I'd vote for getting rid of ChangeLog files.

> | I'd have to think about that one.  But the advantage of organizing
> | by date patched is that when one knows roughly when something
> | stopped working s/he can quickly surmise what may have changed to
> | cause the problem.
>
> Yes, that's a good reason for the ChangeLog entries to have the date
> when the patch was applied.
>

Using my approach, the entries bear their date of origin, but are
sorted in the order they were applied, which I always found enough for
all practical matters.

> I think we avoid these issues if we do away with hand-edited ChangeLog
> files and simply generate them from the Mercurial archive when we make
> releases.
>

Sure; but what to do with the existing ChangeLog files? Can they be
imported somehow into Mercurial? Can Savannah handle this? If we just
leave them, the result will be sort of messy, won't it?

> jwe
>



--
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

John W. Eaton
Administrator
On  6-Jan-2009, Jaroslav Hajek wrote:

| Now that's an idea I really don't like (because of the amount of
| manual editing it brings).
| In that case, I'd vote for getting rid of ChangeLog files.

Yes, I know it is extra work (I've done a lot of it).  But it is
easier than always inserting the ChangeLog entires separately (i.e.,
if they are not included in the diffs).

| Using my approach, the entries bear their date of origin, but are
| sorted in the order they were applied, which I always found enough for
| all practical matters.

To me, that is just confusing because it looks like the entries are
sorted incorrectly.

| Sure; but what to do with the existing ChangeLog files? Can they be
| imported somehow into Mercurial? Can Savannah handle this? If we just
| leave them, the result will be sort of messy, won't it?

We keep the old ChangeLog files with names like ChangeLog.1, same as
we always have.

The information in the generated ChangeLog files is only from after
the time of the switch.

jwe
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

Jaroslav Hajek-2
On Tue, Jan 6, 2009 at 1:45 PM, John W. Eaton <[hidden email]> wrote:

> On  6-Jan-2009, Jaroslav Hajek wrote:
>
> | Now that's an idea I really don't like (because of the amount of
> | manual editing it brings).
> | In that case, I'd vote for getting rid of ChangeLog files.
>
> Yes, I know it is extra work (I've done a lot of it).  But it is
> easier than always inserting the ChangeLog entires separately (i.e.,
> if they are not included in the diffs).
>
> | Using my approach, the entries bear their date of origin, but are
> | sorted in the order they were applied, which I always found enough for
> | all practical matters.
>
> To me, that is just confusing because it looks like the entries are
> sorted incorrectly.
>
> | Sure; but what to do with the existing ChangeLog files? Can they be
> | imported somehow into Mercurial? Can Savannah handle this? If we just
> | leave them, the result will be sort of messy, won't it?
>
> We keep the old ChangeLog files with names like ChangeLog.1, same as
> we always have.
>
> The information in the generated ChangeLog files is only from after
> the time of the switch.
>

OK, I'm fine with this solution. So, shall we do it now?


--
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

John W. Eaton
Administrator
In reply to this post by Thorsten Meyer
On  5-Jan-2009, Thorsten Meyer wrote:

| Here is an example of the output of hg log -style ChangeLog for a larger
| patch:
| 2008-12-27  Jaroslav Hajek  <[hidden email]>
|
|         * src/ChangeLog, src/oct-obj.cc, src/oct-obj.h, src/ov-base-diag.cc,
|         src/ov-base-diag.h, src/ov-base-scalar.cc, src/ov-base.h, src/ov-
|         bool-mat.cc, src/ov-bool-mat.h, src/ov-bool-sparse.cc, src/ov-bool-
|         [...]
|         src/ov-scalar.h, src/ov-str-mat.cc, src/ov-str-mat.h, src/ov.h:
|         remove valid_as_scalar_index
|         [f00578b495e9]

Hmm.  It is bad that the default format breaks filenames as that would
cause trouble for searching.  That should be fixed so that filenames
are never split.

| Now imagine this patch does 5 different kind of changes in 5 groups of
| files to accomplish one major change. How should the ChangeLog look in
| this case?
| I think, it should still look like a list with 5 items for the 5 groups
| of files. Is that possible with mercurial? For example, is it possible
| to define a new style that will output (in ChangeLog format) only the
| commit message  but not the list of files?

The changelog style for Mercurial is apparently just a template
definition, so I think that should be possible.  But even so, I don't
see the problem.  We don't have to write the list of files by hand,
and in a way it is better than the current hand-edited files because
it lists all files that were changed (I'll bet we often omit some in
the hand-edited log entries).

| into the commit message what we used to write into the ChangeLog files
| preceded by another item, maybe like this:
|
| purpose: fix a major bug
|   * src/file1, src/file2: added this
|   * scripts/file3, scripts/file4: removed that
|   * doc/interpreter/file5: updated something else

Yes, to get something that approximates ChangeLogs that follow the GNU
conventions, we would need to write something like you show.  I would
do it like this:

  one line summary

  * file1.cc (function): What changed.
  (other_function): Other change.
  * file2.cc (function): Another change.

Then it would show up in the generated changelog file as

  2009-01-06  John W. Eaton  <[hidden email]>

          * file1.cc, file2.cc:
          one line summary

          * file1.cc (function): What changed. (other_function): Other change.
          * file2.cc (function): Another change.
          [f7a80a86bc8f] [tip]

For me, I think that is close enough if it also simplifies the way we
work.

The disadvantages I see are that this amount of information can't
easily be entered at the command line (with hg commit -m "...").  So I
would probably work like this:

  * make some changes

  * edit a temporary file that has the log message in the format shown
    above, but without any leading spaces

  * commit the change with "hg commit -l tmp-file"

Unfortunately, the Emacs ChangeLog mode is not quite the right thing
for the format of the log message (I would rather not give up M-x
add-change-log-entry...), but one could just use that then strip out
the date/user information and the leading whitespace.  It would be easy
enough to write a simple function to do that, and probably not much
harder to customize the Emacs ChangeLog mode to make editing these log
entries easier.  If you are not using Emacs, then I suppose you are
either already editing ChangeLogs entirely by hand, or you could adapt
whatever tools your editor has in a similar way.

jwe
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

Jaroslav Hajek-2
On Tue, Jan 6, 2009 at 2:14 PM, John W. Eaton <[hidden email]> wrote:

> On  5-Jan-2009, Thorsten Meyer wrote:
>
> | Here is an example of the output of hg log -style ChangeLog for a larger
> | patch:
> | 2008-12-27  Jaroslav Hajek  <[hidden email]>
> |
> |         * src/ChangeLog, src/oct-obj.cc, src/oct-obj.h, src/ov-base-diag.cc,
> |         src/ov-base-diag.h, src/ov-base-scalar.cc, src/ov-base.h, src/ov-
> |         bool-mat.cc, src/ov-bool-mat.h, src/ov-bool-sparse.cc, src/ov-bool-
> |         [...]
> |         src/ov-scalar.h, src/ov-str-mat.cc, src/ov-str-mat.h, src/ov.h:
> |         remove valid_as_scalar_index
> |         [f00578b495e9]
>
> Hmm.  It is bad that the default format breaks filenames as that would
> cause trouble for searching.  That should be fixed so that filenames
> are never split.
>
> | Now imagine this patch does 5 different kind of changes in 5 groups of
> | files to accomplish one major change. How should the ChangeLog look in
> | this case?
> | I think, it should still look like a list with 5 items for the 5 groups
> | of files. Is that possible with mercurial? For example, is it possible
> | to define a new style that will output (in ChangeLog format) only the
> | commit message  but not the list of files?
>
> The changelog style for Mercurial is apparently just a template
> definition, so I think that should be possible.  But even so, I don't
> see the problem.  We don't have to write the list of files by hand,
> and in a way it is better than the current hand-edited files because
> it lists all files that were changed (I'll bet we often omit some in
> the hand-edited log entries).
>
> | into the commit message what we used to write into the ChangeLog files
> | preceded by another item, maybe like this:
> |
> | purpose: fix a major bug
> |   * src/file1, src/file2: added this
> |   * scripts/file3, scripts/file4: removed that
> |   * doc/interpreter/file5: updated something else
>
> Yes, to get something that approximates ChangeLogs that follow the GNU
> conventions, we would need to write something like you show.  I would
> do it like this:
>
>  one line summary
>
>  * file1.cc (function): What changed.
>  (other_function): Other change.
>  * file2.cc (function): Another change.
>
> Then it would show up in the generated changelog file as
>
>  2009-01-06  John W. Eaton  <[hidden email]>
>
>          * file1.cc, file2.cc:
>          one line summary
>
>          * file1.cc (function): What changed. (other_function): Other change.
>          * file2.cc (function): Another change.
>          [f7a80a86bc8f] [tip]
>
> For me, I think that is close enough if it also simplifies the way we
> work.
>
> The disadvantages I see are that this amount of information can't
> easily be entered at the command line (with hg commit -m "...").  So I
> would probably work like this:
>
>  * make some changes
>
>  * edit a temporary file that has the log message in the format shown
>    above, but without any leading spaces
>
>  * commit the change with "hg commit -l tmp-file"
>

qrefresh supports -e, which launches an editor for the message. import
does not support -e, but I guess I could add it easily.


> Unfortunately, the Emacs ChangeLog mode is not quite the right thing
> for the format of the log message (I would rather not give up M-x
> add-change-log-entry...), but one could just use that then strip out
> the date/user information and the leading whitespace.  It would be easy
> enough to write a simple function to do that, and probably not much
> harder to customize the Emacs ChangeLog mode to make editing these log
> entries easier.  If you are not using Emacs, then I suppose you are
> either already editing ChangeLogs entirely by hand, or you could adapt
> whatever tools your editor has in a similar way.
>
> jwe
>



--
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz
Reply | Threaded
Open this post in threaded view
|

Re: ChangeLogs

John W. Eaton
Administrator
In reply to this post by John W. Eaton
On  6-Jan-2009, John W. Eaton wrote:

| The disadvantages I see are that this amount of information can't

One other potential problem is that although currently we can fix up
ChangeLog entries if they are incomplete or in error, I don't think
there is any way to do that with the Mercurial log messages.  Or am I
missing something?

jwe

123