unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#7548: 23.2.90; bookmark-default-handler wrong documentation
@ 2010-12-04  5:45 Leo
  2010-12-05 14:14 ` Leo
  2010-12-08  8:12 ` bug#7548: [FIXED] " Karl Fogel
  0 siblings, 2 replies; 12+ messages in thread
From: Leo @ 2010-12-04  5:45 UTC (permalink / raw)
  To: 7548


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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: 23.2.90; bookmark-default-handler wrong documentation
  2010-12-04  5:45 bug#7548: 23.2.90; bookmark-default-handler wrong documentation Leo
@ 2010-12-05 14:14 ` Leo
  2010-12-08  8:12 ` bug#7548: [FIXED] " Karl Fogel
  1 sibling, 0 replies; 12+ messages in thread
From: Leo @ 2010-12-05 14:14 UTC (permalink / raw)
  To: 7548; +Cc: Karl Fogel, Thierry Volpiatto

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 
================================





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-04  5:45 bug#7548: 23.2.90; bookmark-default-handler wrong documentation Leo
  2010-12-05 14:14 ` Leo
@ 2010-12-08  8:12 ` Karl Fogel
  2010-12-10  8:55   ` Leo
  1 sibling, 1 reply; 12+ messages in thread
From: Karl Fogel @ 2010-12-08  8:12 UTC (permalink / raw)
  To: 7548-done

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
------------------------------------------------------------





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-08  8:12 ` bug#7548: [FIXED] " Karl Fogel
@ 2010-12-10  8:55   ` Leo
  2010-12-12 16:58     ` Karl Fogel
  0 siblings, 1 reply; 12+ messages in thread
From: Leo @ 2010-12-10  8:55 UTC (permalink / raw)
  To: 7548; +Cc: kfogel, Chong Yidong

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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-10  8:55   ` Leo
@ 2010-12-12 16:58     ` Karl Fogel
  2010-12-12 20:26       ` Eli Zaretskii
  0 siblings, 1 reply; 12+ messages in thread
From: Karl Fogel @ 2010-12-12 16:58 UTC (permalink / raw)
  To: Leo; +Cc: 7548, Chong Yidong

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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-12 16:58     ` Karl Fogel
@ 2010-12-12 20:26       ` Eli Zaretskii
  2010-12-12 20:47         ` Karl Fogel
  0 siblings, 1 reply; 12+ messages in thread
From: Eli Zaretskii @ 2010-12-12 20:26 UTC (permalink / raw)
  To: Karl Fogel; +Cc: cyd, 7548, sdl.web

> 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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-12 20:26       ` Eli Zaretskii
@ 2010-12-12 20:47         ` Karl Fogel
  2010-12-12 22:28           ` Eli Zaretskii
                             ` (3 more replies)
  0 siblings, 4 replies; 12+ messages in thread
From: Karl Fogel @ 2010-12-12 20:47 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: cyd, 7548, sdl.web

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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-12 20:47         ` Karl Fogel
@ 2010-12-12 22:28           ` Eli Zaretskii
  2010-12-12 22:31           ` Eli Zaretskii
                             ` (2 subsequent siblings)
  3 siblings, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2010-12-12 22:28 UTC (permalink / raw)
  To: Karl Fogel; +Cc: cyd, 7548, sdl.web






^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-12 20:47         ` Karl Fogel
  2010-12-12 22:28           ` Eli Zaretskii
@ 2010-12-12 22:31           ` Eli Zaretskii
  2010-12-13  0:35           ` Glenn Morris
  2010-12-13 17:16           ` Stefan Monnier
  3 siblings, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2010-12-12 22:31 UTC (permalink / raw)
  To: Karl Fogel; +Cc: cyd, 7548, sdl.web

> 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.





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-12 20:47         ` Karl Fogel
  2010-12-12 22:28           ` Eli Zaretskii
  2010-12-12 22:31           ` Eli Zaretskii
@ 2010-12-13  0:35           ` Glenn Morris
  2010-12-13  2:56             ` Glenn Morris
  2010-12-13 17:16           ` Stefan Monnier
  3 siblings, 1 reply; 12+ messages in thread
From: Glenn Morris @ 2010-12-13  0:35 UTC (permalink / raw)
  To: Karl Fogel; +Cc: cyd, 7548, sdl.web


>>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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-13  0:35           ` Glenn Morris
@ 2010-12-13  2:56             ` Glenn Morris
  0 siblings, 0 replies; 12+ messages in thread
From: Glenn Morris @ 2010-12-13  2:56 UTC (permalink / raw)
  To: Karl Fogel, Eli Zaretskii, Chong Yidong, 7548, Leo


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.





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#7548: [FIXED] bookmark-default-handler wrong documentation
  2010-12-12 20:47         ` Karl Fogel
                             ` (2 preceding siblings ...)
  2010-12-13  0:35           ` Glenn Morris
@ 2010-12-13 17:16           ` Stefan Monnier
  3 siblings, 0 replies; 12+ messages in thread
From: Stefan Monnier @ 2010-12-13 17:16 UTC (permalink / raw)
  To: Karl Fogel; +Cc: cyd, 7548, sdl.web

> 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





^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2010-12-13 17:16 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2010-12-04  5:45 bug#7548: 23.2.90; bookmark-default-handler wrong documentation Leo
2010-12-05 14:14 ` Leo
2010-12-08  8:12 ` bug#7548: [FIXED] " Karl Fogel
2010-12-10  8:55   ` Leo
2010-12-12 16:58     ` Karl Fogel
2010-12-12 20:26       ` Eli Zaretskii
2010-12-12 20:47         ` Karl Fogel
2010-12-12 22:28           ` Eli Zaretskii
2010-12-12 22:31           ` Eli Zaretskii
2010-12-13  0:35           ` Glenn Morris
2010-12-13  2:56             ` Glenn Morris
2010-12-13 17:16           ` Stefan Monnier

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).