bug#7548: 23.2.90; bookmark-default-handler wrong documentation

bug#7548: 23.2.90; bookmark-default-handler wrong documentation

[Leo]

As far as I can tell the arg BMK-RECORD to bookmark-default-handler is
not a bookmark record but a BOOKMARK. This is probably leftover. Could
someone correct this? Thanks.

Leo

bug#7548: 23.2.90; bookmark-default-handler wrong documentation

[Leo]

On 2010-12-04 05:45 +0000, Leo wrote:
> As far as I can tell the arg BMK-RECORD to bookmark-default-handler is
> not a bookmark record but a BOOKMARK. This is probably leftover. Could
> someone correct this? Thanks.
>
> Leo

Posted on Theirry's behalf.

================================
Leo <sdl.web@gmail.com> writes:

> Hello Thierry,
>
> I am wondering if you have time to comment on
> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=7548.

Yes indeed, in bookmark-default-handler but also on other places in
bookmark.el, the argument "bookmark" is confusing.
It refer sometime to a "bookmark-name" and sometimes to a
"bookmark-record".
That is a vestige of old version of `bookmark-prop-get' that was
accepting only "bookmark-record".
But now `bookmark-prop-get' accept both, so such comments in docstring
are no more needed.
Also the arg "bookmark" should be "bookmark-name" or "bookmark-record"
instead of "bookmark".
All functions bookmark-get-* are calling `bookmark-prop-get'.

,----[ Exemple ]
| (bookmark-prop-get '("Any comment on bug #7548 "
|                      (visits . 0)
|                      (time . 1291556487.101218)
|                      (position . 219)
|                      (location . "Gnus-art nnimap+gmail:INBOX:12912:<m1vd389yjo.fsf@cam.ac.uk>")
|                      (group . "nnimap+gmail:INBOX")
|                      (article . 12912)
|                      (message-id . "<m1vd389yjo.fsf@cam.ac.uk>")
|                      (handler . gnus-summary-bookmark-jump))
|                    'handler)
| ==>gnus-summary-bookmark-jump
| 
| (bookmark-prop-get "Any comment on bug #7548 " 'handler)
| ==>gnus-summary-bookmark-jump
`----

Maybe you can forward this to emacs-bug?

> Thanks.
>
> Leo

-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 
================================

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Karl Fogel]

Thanks, Leo and Theirry.  Fixed in bzr rev 102609.  Specifically:

------------------------------------------------------------
revno: 102609
revision-id: kfogel@red-bean.com-20101208080927-5j9jqnb2xvcw4ogm
parent: rgm@gnu.org-20101208050012-qhxovv7ey54v8w3h
committer: Karl Fogel <kfogel@red-bean.com>
branch nick: trunk
timestamp: Wed 2010-12-08 03:09:27 -0500
message:
  Adjust parameter names and doc strings to resolve confusion over
  whether "bookmark" meant a bookmark name or a bookmark record.
  Along the way, shorten one function's name for similar reasons.
  
  (Issue #7548)
  
  * lisp/bookmark.el
    (bookmark-name-from-record):
      New name for `bookmark-name-from-full-record'.  All callers changed.
    (bookmark-get-bookmark, bookmark-get-bookmark-record,
     bookmark-default-annotation-text, bookmark-prop-get, bookmark-prop-set,
     bookmark-get-annotation, bookmark-set-annotation,
     bookmark-get-filename, bookmark-set-filename,
     bookmark-get-position, bookmark-set-position,
     bookmark-get-front-context-string, bookmark-set-front-context-string,
     bookmark-get-rear-context-string, bookmark-set-rear-context-string,
     bookmark-get-handler, bookmark-edit-annotation, bookmark--jump-via,
     bookmark-handle-bookmark, bookmark-location, bookmark-show-annotation):
      Rename `bookmark' parameter to `bookmark-name-or-record', to
      clearly show its role, and shorten or adjust doc strings accordingly.
    (bookmark-set-name):
      Same, and pass the parameter directly to `bookmark-get-bookmark'
      instead of redundantly doing the callee's work.
    (bookmark-default-annotation-text, bookmark-send-edited-annotation,
     bookmark-relocate, bookmark-insert-location, bookmark-insert,
     bookmark-delete):
      Rename `bookmark' parameter to `bookmark-name', and in some cases
      shorten doc string accordingly.
    (bookmark-rename):
      Change `old' and `new' parameters to `old-name'
      and `new-name', and adjust an internal variable to avoid confusion.
    (bookmark-jump, bookmark-jump-noselect):
      Clarify `bookmark' parameter in doc string.
modified:
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/bookmark.el               bookmark.el-20091113204419-o5vbwnq5f7feedwu-621
------------------------------------------------------------

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Leo]

On 2010-12-08 08:12 +0000, Karl Fogel wrote:
> Thanks, Leo and Theirry.  Fixed in bzr rev 102609.  Specifically:

I wonder if this can be moved to 23.3.

Thanks.
-- 
Leo

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Karl Fogel]

Leo <sdl.web@gmail.com> writes:
>On 2010-12-08 08:12 +0000, Karl Fogel wrote:
>> Thanks, Leo and Theirry.  Fixed in bzr rev 102609.  Specifically:
>
>I wonder if this can be moved to 23.3.

I generally just put things on trunk and trust they will make it into a
release at some point.  However, if you can point me to some
documentation about the proper way to put things on release branches, I
would do that (I haven't been able to find such docs in the tree, but
maybe I'm not looking in the right places).

Best,
-Karl

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Date: Sun, 12 Dec 2010 11:58:04 -0500
> Cc: 7548@debbugs.gnu.org, Chong Yidong <cyd@stupidchicken.com>
> 
> Leo <sdl.web@gmail.com> writes:
> >On 2010-12-08 08:12 +0000, Karl Fogel wrote:
> >> Thanks, Leo and Theirry.  Fixed in bzr rev 102609.  Specifically:
> >
> >I wonder if this can be moved to 23.3.
> 
> I generally just put things on trunk and trust they will make it into a
> release at some point.

We generally do it the other way around: changes that are safe for the
release branch should be committed there, and they will then be merged
to the trunk (unless you instruct otherwise, see below).

> However, if you can point me to some
> documentation about the proper way to put things on release branches

It's very simple:

 . create a clone of the "emacs-23" branch ("bzr branch --bind")
 . commit changes that are appropriate there instead of to the trunk
 . if a change committed to the branch should not be merged to the
   trunk, put some prominent verbiage into the log message
 . commit to the trunk only changes that are inappropriate for the
   release branch

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>> I generally just put things on trunk and trust they will make it into a
>> release at some point.
>
>We generally do it the other way around: changes that are safe for the
>release branch should be committed there, and they will then be merged
>to the trunk (unless you instruct otherwise, see below).

Is this documented somewhere?

(I think I recall having this discussion on-list before.)  If one just
always commits to trunk, then one doesn't have to ponder whether one's
changes are safe for the upcoming release or not -- one knows the
changes will eventually make it into mainline releases.  Since these
changes were about the long-term health of bookmark.el, and were not
bugfixes intended for this particular release, committing to trunk seems
like the better route in this case anyway.

>> However, if you can point me to some
>> documentation about the proper way to put things on release branches
>
>It's very simple:
>
> . create a clone of the "emacs-23" branch ("bzr branch --bind")
> . commit changes that are appropriate there instead of to the trunk
> . if a change committed to the branch should not be merged to the
>   trunk, put some prominent verbiage into the log message
> . commit to the trunk only changes that are inappropriate for the
>   release branch

This gets us closer to documentation; once honed, I can put it in a file
in the tree somewhere findable.  But first:

Where does a developer look in order to find out that we're currently in
a "commit to branches not to trunk" state?  In other words, how would I
know that today I should branch from the 'emacs-23' branch instead of
trunk, but that tomorrow (or whenever) trunk is the default again?

One can watch the mailing list, but it's rather high traffic, and doing
it that way makes us keep state in our heads -- error-prone -- that
could instead be maintained by machines.  For example: during this
period, trunk could simply reject changes whose commit message doesn't
contain a special string, and the rejection message would contain
instructions explaining what branch to commit to instead, and what the
special string to use is if one really needs to commit to trunk.  (I
don't know how to set that up in bzr, though.)

-Karl

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Eli Zaretskii]

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: sdl.web@gmail.com,  7548@debbugs.gnu.org,  cyd@stupidchicken.com
> Date: Sun, 12 Dec 2010 15:47:26 -0500
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> >> I generally just put things on trunk and trust they will make it into a
> >> release at some point.
> >
> >We generally do it the other way around: changes that are safe for the
> >release branch should be committed there, and they will then be merged
> >to the trunk (unless you instruct otherwise, see below).
> 
> Is this documented somewhere?

I think Stefan posted something like that here, but I cannot find it
now.

> (I think I recall having this discussion on-list before.)  If one just
> always commits to trunk, then one doesn't have to ponder whether one's
> changes are safe for the upcoming release or not -- one knows the
> changes will eventually make it into mainline releases.  Since these
> changes were about the long-term health of bookmark.el, and were not
> bugfixes intended for this particular release, committing to trunk seems
> like the better route in this case anyway.

The decision whether a particular change is important enough to have
in the next bugfix release is up to you; I just answered your
question.

> Where does a developer look in order to find out that we're currently in
> a "commit to branches not to trunk" state?

We are always in that state.  Changes that are safe for the branch
should be committed there at all times.  The branch is merged to the
trunk periodically.

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Glenn Morris]

>>We generally do it the other way around: changes that are safe for the
>>release branch should be committed there, and they will then be merged
>>to the trunk (unless you instruct otherwise, see below).
>
> Is this documented somewhere?

admin/notes/bzr

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Glenn Morris]

BTW; ideas for improving this:

i) create an emacs-devel-announce list, automatically subscribe
everybody with commit rights

ii) create an "announce" topic for the emacs-devel list, and require
anyone with commit rights to at least receive messages in that topic.

But both of these require the maintainers to remember to use the
"announce" list/topic for announcements.

bug#7548: [FIXED] bookmark-default-handler wrong documentation

[Stefan Monnier]

> changes will eventually make it into mainline releases.  Since these
> changes were about the long-term health of bookmark.el, and were not
> bugfixes intended for this particular release, committing to trunk seems
> like the better route in this case anyway.

I'd tend to agree.


        Stefan