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