From: Karl Fogel <email@example.com> To: Ihor Radchenko <firstname.lastname@example.org> Cc: Org Mode <email@example.com> Subject: Re: Removing obsolete function `org-truely-invisible-p'. Date: Thu, 07 Apr 2022 11:57:50 -0500 [thread overview] Message-ID: <firstname.lastname@example.org> (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 <email@example.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
next prev parent 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 \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.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).