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

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

[Karl Fogel]

The function `org-truely-invisible-p' is defined in 
'lisp/org-macs.el', but it is not used anywhere anymore in Org 
Mode, nor is it used anywhere in GNU Emacs (I checked on both 
'emacs-28' branch and 'master' branch).

The last (and possibly only?) call to that function was removed 
from `org-beginning-of-line' in this commit:

  commit 3baf246f4f73005a4eacd7c368f7222f95d50243
  Author:     Nicolas Goaziou <mail@nicolasgoaziou.fr>
  AuthorDate: Thu Apr 28 23:28:15 2016 +0200
  Commit:     Nicolas Goaziou <mail@nicolasgoaziou.fr>
  CommitDate: Thu Apr 28 23:28:15 2016 +0200
  
      Handle correctly `shift-select-mode'
      
      * lisp/org.el (org-beginning-of-line): Handle correctly 
      `shift-select-mode'.
      
      Reported-by: Mathieu Marques <mathieumarques78@gmail.com>
      <http://permalink.gmane.org/gmane.emacs.orgmode/106783>

Then, a few months later in commit 87116700e6e, Nicholas moved the 
function to 'org-macs.el', where it has been sitting unused ever 
since.

Should we just remove `org-truely-invisible-p'?  Or at least 
correct the spelling of its name ("truely" should be "truly")?

It seems fairly unlikely to me that people are using it in their 
own code, although of course I cannot be sure of that.  Partly, I 
believe that because surely someone else would have noticed the 
misspelling by now, if enough people were using it :-).

Best regards,
-Karl

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

[Samuel Wales]

idk and will go along with whatever developers decide, but your note
was a good reminder that visible mode can be checked.

also made me wonder if it is possible to move anything from org-macs
out to topic-specific files like org-visibility.el or so?  no?

[idk what org visibility functions do what.  although i suspect org
can do it, i still use htmlize-buffer-substring-no-invisible.]


On 12/4/21, Karl Fogel <kfogel@red-bean.com> wrote:
> The function `org-truely-invisible-p' is defined in
> 'lisp/org-macs.el', but it is not used anywhere anymore in Org
> Mode, nor is it used anywhere in GNU Emacs (I checked on both
> 'emacs-28' branch and 'master' branch).
>
> The last (and possibly only?) call to that function was removed
> from `org-beginning-of-line' in this commit:
>
>   commit 3baf246f4f73005a4eacd7c368f7222f95d50243
>   Author:     Nicolas Goaziou <mail@nicolasgoaziou.fr>
>   AuthorDate: Thu Apr 28 23:28:15 2016 +0200
>   Commit:     Nicolas Goaziou <mail@nicolasgoaziou.fr>
>   CommitDate: Thu Apr 28 23:28:15 2016 +0200
>
>       Handle correctly `shift-select-mode'
>
>       * lisp/org.el (org-beginning-of-line): Handle correctly
>       `shift-select-mode'.
>
>       Reported-by: Mathieu Marques <mathieumarques78@gmail.com>
>       <http://permalink.gmane.org/gmane.emacs.orgmode/106783>
>
> Then, a few months later in commit 87116700e6e, Nicholas moved the
> function to 'org-macs.el', where it has been sitting unused ever
> since.
>
> Should we just remove `org-truely-invisible-p'?  Or at least
> correct the spelling of its name ("truely" should be "truly")?
>
> It seems fairly unlikely to me that people are using it in their
> own code, although of course I cannot be sure of that.  Partly, I
> believe that because surely someone else would have noticed the
> misspelling by now, if enough people were using it :-).
>
> Best regards,
> -Karl
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

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

[Ihor Radchenko]

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

> Should we just remove `org-truely-invisible-p'?  Or at least 
> correct the spelling of its name ("truely" should be "truly")?

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.

Could you prepare a patch? Having a patch may encourage more feedback.

Best,
Ihor

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

[Karl Fogel]

[-- Attachment #1: Type: text/plain, Size: 679 bytes --]

On 19 Dec 2021, Ihor Radchenko wrote:
>Karl Fogel <kfogel@red-bean.com> writes:
>
>> Should we just remove `org-truely-invisible-p'?  Or at least 
>> correct the spelling of its name ("truely" should be "truly")?
>
>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.
>
>Could you prepare a patch? Having a patch may encourage more 
>feedback.

Sure; please see attached.

Best regards,
-Karl


[-- Attachment #2: 0001-Mark-function-obsolete-fix-spelling-of-its-name.patch --]
[-- Type: text/plain, Size: 2621 bytes --]

From bb229b4f8f78ae52962d7bc90c8b1d4993af8263 Mon Sep 17 00:00:00 2001
From: Karl Fogel <kfogel@red-bean.com>
Date: Thu, 31 Mar 2022 19:02:38 -0500
Subject: [PATCH] Mark function obsolete & fix spelling of its name

* lisp/org-macs.el (org-truely-invisible-p): Move to...
* lisp/org-compat.el (org-truly-invisible-p): ...here, and add...
  (org-truely-invisible-p): ...this compatibility alias.

There are no callers of this function in Org Mode, nor in current
Emacs (on the 'master and 'emacs-28' branches at least).  We discussed
whether to remove it entirely, and for now seem to have tentatively
decided not to remove it.  See this thread for more details:

  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>
---
 lisp/org-compat.el | 12 ++++++++++++
 lisp/org-macs.el   |  7 -------
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git lisp/org-compat.el lisp/org-compat.el
index 38d330de6..43d44211e 100644
--- lisp/org-compat.el
+++ lisp/org-compat.el
@@ -402,6 +402,18 @@ See `org-link-parameters' for documentation on the other parameters."
 (make-obsolete 'org-add-link-type "use `org-link-set-parameters' instead." "9.0")
 
 ;;;; Functions unused in Org core.
+
+;; Not used since commit 3baf246f4f (Nicolas Goaziou, 2016-04-28)
+(defun org-truly-invisible-p ()
+  "Check if point is at a character currently not visible.
+This version does not only check the character property, but also
+`visible-mode'."
+  (unless (bound-and-true-p visible-mode)
+    (org-invisible-p)))
+(define-obsolete-function-alias 'org-truely-invisible-p
+  'org-truly-invisible-p "2022-03-31"
+  "Compatibility alias for legacy misspelling of `org-truly-invisible-p'.")
+
 (defun org-table-recognize-table.el ()
   "If there is a table.el table nearby, recognize it and move into it."
   (when (org-at-table.el-p)
diff --git lisp/org-macs.el lisp/org-macs.el
index b39af9103..fb3c441e1 100644
--- lisp/org-macs.el
+++ lisp/org-macs.el
@@ -1151,13 +1151,6 @@ fontification."
 	  (folding-only (memq value '(org-hide-block outline)))
 	  (t value))))
 
-(defun org-truely-invisible-p ()
-  "Check if point is at a character currently not visible.
-This version does not only check the character property, but also
-`visible-mode'."
-  (unless (bound-and-true-p visible-mode)
-    (org-invisible-p)))
-
 (defun org-invisible-p2 ()
   "Check if point is at a character currently not visible.
 If the point is at EOL (and not at the beginning of a buffer too),
-- 
2.35.1

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

[Ihor Radchenko]

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

>>Could you prepare a patch? Having a patch may encourage more 
>>feedback.
>
> Sure; please see attached.

Thanks! Marking your message as a patch to be tracked at
updates.orgmode.org

> From bb229b4f8f78ae52962d7bc90c8b1d4993af8263 Mon Sep 17 00:00:00 2001
> From: Karl Fogel <kfogel@red-bean.com>
> Date: Thu, 31 Mar 2022 19:02:38 -0500
> 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"

> * lisp/org-macs.el (org-truely-invisible-p): Move to...
> * lisp/org-compat.el (org-truly-invisible-p): ...here, and add...
>   (org-truely-invisible-p): ...this compatibility alias.

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.

>   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

Best,
Ihor

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

[Karl Fogel]

On 04 Apr 2022, Ihor Radchenko wrote:
>> From bb229b4f8f78ae52962d7bc90c8b1d4993af8263 Mon Sep 17 
>> 00:00:00 2001
>> From: Karl Fogel <kfogel@red-bean.com>
>> Date: Thu, 31 Mar 2022 19:02:38 -0500
>> 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"
>
>> * lisp/org-macs.el (org-truely-invisible-p): Move to...
>> * lisp/org-compat.el (org-truly-invisible-p): ...here, and 
>> add...
>>   (org-truely-invisible-p): ...this compatibility alias.

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.

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

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

Best regards,
-Karl

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

[Ihor Radchenko]

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

Linking by Message-ID

[Max Nikulin]

On 05/04/2022 13:14, Ihor Radchenko wrote:
> Karl Fogel writes:
> 
>>>>    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.

A link to a message in the local storage of a regular mail reader should 
have mid: scheme, e.g. mid:87h7b5rm6f.fsf@localhost
https://tools.ietf.org/html/rfc2392
RFC 2392 - Content-ID and Message-ID Uniform Resource Locators

Unfortunately the only way to specify mail list is the text around the link.

Mail-archive promises Message-ID resolver 
https://mid.mail-archive.com/... but it does not work for emacs-orgmode. 
Gmane has the org mail list archive and allows access using Message-ID 
from an arbitrary mail list:

     w3m -m 'nntp://news.gmane.io/87h7b5rm6f.fsf@localhost'

However I consider https://list.orgmode.org/MID links as more friendly 
for users unaware of possible ways to obtain some message using its 
Message-ID.

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

[Karl Fogel]

[-- Attachment #1: Type: text/plain, Size: 3209 bytes --]

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


[-- Attachment #2: 0001-lisp-org-macs.el-Fix-spelling-of-org-truly-invisible.patch --]
[-- Type: text/plain, Size: 1472 bytes --]

From 2cef1fdbe2b2aa40a2bb081eab4b2e2808000670 Mon Sep 17 00:00:00 2001
From: Karl Fogel <kfogel@red-bean.com>
Date: Thu, 31 Mar 2022 19:02:38 -0500
Subject: [PATCH] lisp/org-macs.el: Fix spelling of `org-truly-invisible-p'

* lisp/org-macs.el (org-truly-invisible-p): Fix spelling of name.
* lisp/org-compat.el (org-truely-invisible-p): Add compatibility
  alias for the old name.
---
 lisp/org-compat.el | 4 ++++
 lisp/org-macs.el   | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git lisp/org-compat.el lisp/org-compat.el
index 38d330de6..00716ae13 100644
--- lisp/org-compat.el
+++ lisp/org-compat.el
@@ -752,6 +752,10 @@ context.  See the individual commands for more information."
 
 (define-obsolete-function-alias 'org-get-last-sibling 'org-get-previous-sibling "9.4")
 
+(define-obsolete-function-alias 'org-truely-invisible-p
+  'org-truly-invisible-p "9.6"
+  "Compatibility alias for legacy misspelling of `org-truly-invisible-p'.")
+
 ;;;; Obsolete link types
 
 (eval-after-load 'ol
diff --git lisp/org-macs.el lisp/org-macs.el
index b39af9103..a09115e7c 100644
--- lisp/org-macs.el
+++ lisp/org-macs.el
@@ -1151,7 +1151,7 @@ fontification."
 	  (folding-only (memq value '(org-hide-block outline)))
 	  (t value))))
 
-(defun org-truely-invisible-p ()
+(defun org-truly-invisible-p ()
   "Check if point is at a character currently not visible.
 This version does not only check the character property, but also
 `visible-mode'."
-- 
2.35.1

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

[Ihor Radchenko]

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

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

Could you elaborate?

We have the following in etc/CONTRIBUTE:

>>> * Main contribution rules
>>> ...
>>> See [[https://orgmode.org/worg/org-contribute.html][worg/org-contribute]] for guidance on how to contribute effectively.

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

Thanks! Merged as d80aa2776 to main.

Best,
Ihor

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

[Karl Fogel]

On 07 Apr 2022, Ihor Radchenko wrote:
>Karl Fogel <kfogel@red-bean.com> writes:
>
>> 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.
>
>Could you elaborate?
>
>We have the following in etc/CONTRIBUTE:
>
>>>> * Main contribution rules
>>>> ...
>>>> See 
>>>> [[https://orgmode.org/worg/org-contribute.html][worg/org-contribute]] 
>>>> for guidance on how to contribute effectively.

Sure, I'll elaborate.

The "..." in your quoted text above contains, among other things, 
this item:

   - Org mode no longer uses ChangeLog entries to document 
   changes. 
     Instead, special commit messages are used, as described in 
     the `CONTRIBUTE' file in the main Emacs repository. 

That item is just one in a list of several items in section 4 
(which is under the top-level heading "Main contribution rules"). 
At the very end of the "Main contribution rules" top-level section 
comes this line:

  See 
  [[https://orgmode.org/worg/org-contribute.html][worg/org-contribute]] 
  for guidance on how to contribute effectively.

So when I went searching in CONTRIBUTE specifically for guidance 
on commit messages, I searched for the string "commit message". 
That took me to the item I quote above, which states pretty 
clearly that the Emacs guidelines apply here.  It does not state 
that there is any other source of guidance about commit messages, 
nor does it say anything to indicate that Org Mode has commit 
message guidelines that are a superset of (i.e., more complicated 
than) Emacs's guidelines.  The string "commit message" does not 
appear anywhere else in Org Mode's CONTRIBUTE file.

So, naturally, after I read that item, I assumed that I was ready 
to write the commit message, since I already knew Emacs's 
guidelines.

Meanhwile, the https://orgmode.org/worg/org-contribute.html page 
is a bit long, and it starts out with a bunch of very generic 
guidance that is not useful to developer contributing a code 
patch.  (I'm not saying that material isn't useful, by the way.  I 
think it's good to have it there.  I'm just saying it doesn't 
provide anything useful to one particular demographic.  But it's 
still good because someone might be making some other kind of 
contribution.)

In that page, the part about "Commit messages and ChangeLog 
entries" starts about three-quarters of the way down.  Virtually 
none of the material preceding it had anything to do with my 
circumstances, and since I had just seen very clear guidance (in 
CONTRIBUTE) about how to write commit messages, I timed out before 
making it that far.

A good solution to this would be to revise the item in CONTRIBUTE 
to make it clear that there is special Org Mode guidance on commit 
messages that goes beyond what Emacs itself wants.  I was too 
tired to go through the process to contribute that change though, 
so instead I wrote this long email :-). 

>Thanks! Merged as d80aa2776 to main.

Thank you very much!

Best regards,
-Karl

[PATCH] CONTRIBUTE: Link WORG page when explaining commit message format

[Ihor Radchenko]

[-- Attachment #1: Type: text/plain, Size: 283 bytes --]

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

> So, naturally, after I read that item, I assumed that I was ready 
> to write the commit message, since I already knew Emacs's 
> guidelines.

Thanks for the detailed explanation!
Attaching tentative patch with clarification.

Best,
Ihor


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-CONTRIBUTE-Link-WORG-page-when-explaining-commit-mes.patch --]
[-- Type: text/x-patch, Size: 1631 bytes --]

From cd5e965d079aa7a3ac842e8ea3ea5762e2d80985 Mon Sep 17 00:00:00 2001
Message-Id: <cd5e965d079aa7a3ac842e8ea3ea5762e2d80985.1650015125.git.yantar92@gmail.com>
From: Ihor Radchenko <yantar92@gmail.com>
Date: Fri, 15 Apr 2022 17:29:47 +0800
Subject: [PATCH] CONTRIBUTE: Link WORG page when explaining commit message
 format

* CONTRIBUTE (Main contribution rules): Link relevant WORG contribute
page section with extra conventions for our commit message guidelines.

See https://orgmode.org/list/87r16896gh.fsf@red-bean.com
---
 CONTRIBUTE | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTE b/CONTRIBUTE
index 94d471a0f..f8a81515e 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -55,8 +55,11 @@ Org maintenance is detailed on Worg: see [[https://orgmode.org/worg/org-maintena
      the [[https://www.gnu.org/philosophy/kind-communication.en.html][GNU Kind Communications Guidelines]].
 
    - Org mode no longer uses ChangeLog entries to document changes.
-     Instead, special commit messages are used, as described in the
-     `CONTRIBUTE' file in the main Emacs repository.
+     Instead, special commit messages are used.  The commit message
+     format generally follows Emacs conventions, as described in the
+     `CONTRIBUTE' file in the main Emacs repository.  Several more
+     Org-specific conventions are described in
+     [[https://orgmode.org/worg/org-contribute.html#commit-messages][worg/org-contribute#commit-messages]].
 
    - Among other things, Org mode is widely appreciated because of its
      simplicity, cleanness and consistency.  We should try to preserve
-- 
2.35.1

Re: [PATCH] CONTRIBUTE: Link WORG page when explaining commit message format

[Robert Pluim]

>>>>> On Fri, 15 Apr 2022 17:33:33 +0800, Ihor Radchenko <yantar92@gmail.com> said:
    Ihor>     - Org mode no longer uses ChangeLog entries to document changes.
    Ihor> -     Instead, special commit messages are used, as described in the
    Ihor> -     `CONTRIBUTE' file in the main Emacs repository.
    Ihor> +     Instead, special commit messages are used.  The commit message
    Ihor> +     format generally follows Emacs conventions, as described in the
    Ihor> +     `CONTRIBUTE' file in the main Emacs repository.  Several more
    Ihor> +     Org-specific conventions are described in
    Ihor> +     [[https://orgmode.org/worg/org-contribute.html#commit-messages][worg/org-contribute#commit-messages]].

It might be good to mention `magit-generate-changelog' there as an
easy way to produce the ChangeLog format entry (it doesnʼt require you
to iterate over the diff hunks, and you can call it from the magit
commit buffer).

Robert
-- 

Re: [PATCH] CONTRIBUTE: Link WORG page when explaining commit message format

[Karl Fogel]

On 15 Apr 2022, Robert Pluim wrote:
>>>>>> On Fri, 15 Apr 2022 17:33:33 +0800, Ihor Radchenko 
>>>>>> <yantar92@gmail.com> said:
>    Ihor>     - Org mode no longer uses ChangeLog entries to 
>    document changes.
>    Ihor> -     Instead, special commit messages are used, as 
>    described in the
>    Ihor> -     `CONTRIBUTE' file in the main Emacs repository.
>    Ihor> +     Instead, special commit messages are used.  The 
>    commit message
>    Ihor> +     format generally follows Emacs conventions, as 
>    described in the
>    Ihor> +     `CONTRIBUTE' file in the main Emacs repository. 
>    Several more
>    Ihor> +     Org-specific conventions are described in
>    Ihor> + 
>    [[https://orgmode.org/worg/org-contribute.html#commit-messages][worg/org-contribute#commit-messages]].
>
>It might be good to mention `magit-generate-changelog' there as 
>an
>easy way to produce the ChangeLog format entry (it doesnʼt 
>require you
>to iterate over the diff hunks, and you can call it from the 
>magit
>commit buffer).

I really like the patch, Ihor -- it's already a big improvement! 
(I haven't tested Robert's suggestion of 
`magit-generate-changelog', but it seems like a reasonable hint to 
include, given Magit's popularity.)

Best regards,
-Karl

Re: [PATCH] CONTRIBUTE: Link WORG page when explaining commit message format

[Ihor Radchenko]

Robert Pluim <rpluim@gmail.com> writes:

> It might be good to mention `magit-generate-changelog' there as an
> easy way to produce the ChangeLog format entry (it doesnʼt require you
> to iterate over the diff hunks, and you can call it from the magit
> commit buffer).

Note that we already mention `magit-commit-add-log` in
https://orgmode.org/worg/org-contribute.html#commit-messages

I personally dislike magit-generate-changelog because it tempts to
document only a single change in a function, even when multiple changes
were made in that function.

However, the command might indeed be useful for others. It could be a
good addition to https://orgmode.org/worg/org-contribute.org I do not
think that magit staff belongs to CONTRIBUTE file directly.
Patches are welcome.

Best,
Ihor

Re: [PATCH] CONTRIBUTE: Link WORG page when explaining commit message format

[Ihor Radchenko]

Applied.

The patch is now on main as 67efaa739.

Best,
Ihor

Re: [PATCH] CONTRIBUTE: Link WORG page when explaining commit message format

[Karl Fogel]

On 23 Apr 2022, Ihor Radchenko wrote:
>Applied.
>The patch is now on main as 67efaa739.

Thanks, Ihor!

Best regards,
-Karl