emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Karl Fogel <kfogel@red-bean.com>
To: Ihor Radchenko <yantar92@gmail.com>
Cc: Org Mode <emacs-orgmode@gnu.org>
Subject: Re: Removing obsolete function `org-truely-invisible-p'.
Date: Thu, 07 Apr 2022 11:57:50 -0500	[thread overview]
Message-ID: <87r16896gh.fsf@red-bean.com> (raw)
In-Reply-To: <87czht7alk.fsf@localhost> (Ihor Radchenko's message of "Thu, 07 Apr 2022 12:59:03 +0800")

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


  reply	other threads:[~2022-04-07 17:03 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
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 [this message]
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=87r16896gh.fsf@red-bean.com \
    --to=kfogel@red-bean.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=yantar92@gmail.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).