emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Ihor Radchenko <yantar92@gmail.com>
To: Karl Fogel <kfogel@red-bean.com>
Cc: Org Mode <emacs-orgmode@gnu.org>
Subject: Re: Removing obsolete function `org-truely-invisible-p'.
Date: Tue, 05 Apr 2022 14:14:05 +0800	[thread overview]
Message-ID: <87ee2cf45u.fsf@localhost> (raw)
In-Reply-To: <8735iskegy.fsf@red-bean.com>

Karl Fogel <kfogel@red-bean.com> writes:

>>> Subject: [PATCH] Mark function obsolete & fix spelling of its 
>>> name
>>
>>This commit message is a bit confusing. I would mention the 
>>function
>>name: "Mark `org-truely-invisible-p' obsolete and fix spelling of 
>>its
>>name"
>
> It does mention both names :-).  But I'm happy to rewrite in the 
> style you suggest above; I was just trying to follow the 
> CONTRIBUTE guidelines.

Sorry for not being clear. I was referring to the commit message - it is
what you commonly see in git log.

Having something like

>>> commit-hash Mark function obsolete & fix spelling of its name

in git log is confusing because it is unclear what the commit is
changing. If you look at
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/log/
then you can see that we generally follow certain style of the
commit messages: changed-file-or-library: What is changed
Also see https://orgmode.org/worg/org-contribute.html#commit-messages

>>It is too much.
>>We can either
>>1. Obsolete org-truely-invisible-p. Then, there is not much point
>>   renaming it.
>>2. Rename it without obsoletion. Then, there is not much point 
>>moving
>>   the function definition to org-compat.
>
> Hmm.  From the prior conversation in this thread, I thought we'd 
> decided to do both.  There are two separate issues here:
>
> 1) The function is no longer used in Org Mode or Emacs.
>
> 2) Unrelatedly, the function's name has a misspelling.
>
> (1) suggests that the function should be moved to 'org-compat.el' 
> (if I understand correctly what that file is for).
>
> (2) is usually fixed with a rename and a compatibility alias -- 
> i.e., this is what we would do for any function, whether used or 
> unused.
>
> In your message 87h7b5rm6f.fsf@localhost of 19 Dec 2021, you 
> wrote:
>
>>I feel slightly reluctant about removal. If nothing, this 
>>function can
>>be a reminder about visible-mode and keeping it has little 
>>downside.
>>Though if others think that removing would be better, I would 
>>also be
>>fine with it.
>> 
>>Renaming sounds reasonable. Just need to define obsolete alias 
>>for the
>>old name in org-compat.el.
>
> My patch was based on the above, and on the fact that obsolete 
> (i.e., unused) functions apparently get moved to org-compat.el, at 
> least based on what I see already in that file.

I think we have a misunderstanding here. Unused functions are not
necessarily obsolete. For example, we have org-list-to-texinfo, which is
not used anywhere in the codebase, but could be useful for developers.

org-compat.el contains functions that are planned for removal in future
(and obsolete for the time being), obsolete function/variable names, and
compatibility functions.

As I mentioned in my previous email, I am slightly reluctant to remove
org-truely-invisible-p. It means that it should remain available and no
plans to remove it should be made (unless there are multiple devs/users
who prefer removal). Hence, the function should stay in org-macs.el.
org-macs.el is meant to store general-purpose functions that can be
useful for development of the whole Org mode ecosystem.

If we decide that org-truely-invisible-p stays in org-macs, we should
fix the issue with its name. Renaming requires creating obsolete
function name alias in org-compat.el to make sure that nothing gets
broken unexpectedly for people who use org-truely-invisible-p with its
current name.

Hope I clarified my logic.

>>>   From: Ihor Radchenko
>>>   Subject: Re: Removing obsolete function 
>>>   `org-truely-invisible-p'.
>>>   To: Karl Fogel
>>>   Cc: Org Mode
>>>   Date: Sun, 19 Dec 2021 17:14:32 +0800
>>>   Message-ID: <87h7b5rm6f.fsf@localhost>
>>
>>I usually just leave an ML link in such cases:
>>https://orgmode.org/list/87h7b5rm6f.fsf@localhost
>
> As long as the ML link contains the Message-ID, as appears to be 
> the case here, yeah.  Mailing list archives can move, which causes 
> links to suddenly stop working.  But if the Message-ID is in the 
> link, then (with a little extra work) one can always find the 
> message in the new archive.
>
> (The reason I typically include more is to make things as easy as 
> possible for those who are searching in a local archive using 
> their regular mailreader.  But I can switch to the above way if 
> you'd prefer.)

FYI, I do not know an easy way to search mailing list archives by
Message-ID. Message-ID itself does not even provide information which
mailing list it is referring to (maybe it is e.g. Emacs devel).
That's why I prefer links - they can often be found using archive.org if
nothing.

On the other hand, extra information would not heart. In addition to
link.

Best,
Ihor


  reply	other threads:[~2022-04-05  6:18 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-12-04 20:53 Karl Fogel
2021-12-04 22:19 ` Samuel Wales
2021-12-19  9:14 ` Ihor Radchenko
2022-04-01  0:28   ` Karl Fogel
2022-04-04 11:55     ` Ihor Radchenko
2022-04-04 16:20       ` Karl Fogel
2022-04-05  6:14         ` Ihor Radchenko [this message]
2022-04-05 17:08           ` Linking by Message-ID Max Nikulin
2022-04-05 18:41           ` Removing obsolete function `org-truely-invisible-p' Karl Fogel
2022-04-07  4:59             ` Ihor Radchenko
2022-04-07 16:57               ` Karl Fogel
2022-04-15  9:33                 ` [PATCH] CONTRIBUTE: Link WORG page when explaining commit message format Ihor Radchenko
2022-04-15 12:47                   ` Robert Pluim
2022-04-15 21:13                     ` Karl Fogel
2022-04-16  9:35                     ` Ihor Radchenko
2022-04-23  8:06                   ` Ihor Radchenko
2022-04-23 15:47                     ` Karl Fogel

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87ee2cf45u.fsf@localhost \
    --to=yantar92@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=kfogel@red-bean.com \
    --subject='Re: Removing obsolete function `org-truely-invisible-p'\''.' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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

	https://git.savannah.gnu.org/cgit/emacs/org-mode.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).