Re: Removing obsolete function `org-truely-invisible-p'.

[Karl Fogel]

On 05 Apr 2022, Ihor Radchenko wrote: 
> 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

Oh, it was clear you were referring to the commit message -- what 
I now realize is that you were referring to the first line of the 
commit message (the summary line).

Unfortunately, the 'CONTRIBUTE' file at the top level of the Org 
Mode source tree gives incomplete guidance on commit messages (it 
just says to follow what Emacs does, so I did that).  I didn't 
realize that 
https://orgmode.org/worg/org-contribute.html#commit-messages has 
further, slightly different guidance.

Thanks.  I'm happy to adhere to the local standards, once I figure 
out what they are :-).

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

You did!

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

Makes sense, yup.  Actually, I usually include the link -- I just 
didn't think of it in this case because I rarely visit the Org 
Mode mailing list archives (unlike the Emacs Devel archives, which 
I often do visit, and therefore my commits in Emacs always include 
the link when referring to a mailing list post).

A revised patch is attached.  Now it's so simple that I think the 
commit message doesn't need to point to the mailing list 
discussion anyway.  Review welcome.

Best regards,
-Karl

0001-lisp-org-macs.el-Fix-spelling-of-org-truly-invisible.patch
Description: Text document