From: Ihor Radchenko <yantar92@posteo.net>
To: 66067@debbugs.gnu.org
Subject: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
Date: Mon, 18 Sep 2023 08:38:44 +0000 [thread overview]
Message-ID: <87cyyfkh9n.fsf@localhost> (raw)
Hi,
When writing the NEWS entry for bug#65469, I was trying to follow the
instructions in CONTRIBUTE file. However, not everything was very clear
and I had to consult the git log, other entries, and do some guess work.
In particular:
1. It is not documented whether new NEWS entries should go in front or
at the end of the news list under the same category.
2. CONTRIBUTE states: "Think about whether your change requires updating
the manuals. If you know it does not, mark the NEWS entry with
"---"."
However, it is not clear what "mark" means. When looking into NEWS
file, I saw things like
* item 1
---
* item 2
...
And it is not clear if "---" refers to item 1 or item 2.
3. "Documenting your changes" section of CONTRIBUTE file refers to
documentation tips section of Elisp manual. However, NEWS file
appears to use a slightly different quoting scheme for variable and
function names. For example,
** 'write-region-inhibit-fsync' now defaults to t in interactive mode,
uses straight quotes '...', not the usual `...' docstring style.
4. I was also confused how to refer to info nodes from NEWS. I found one
example in
For more information, see the "(eshell) Built-ins" node in the Eshell
manual.
but the convention is not documented anywhere.
I _guessed_ that the quoting should be similar to docstring style,
but using "..." quotes instead of `...' and adding space in
"(manual) Section" instead of `(manual)Section' used in the
docstrings.
I believe that the above and any other conventions should be explained
better.
In GNU Emacs 30.0.50 (build 3, x86_64-pc-linux-gnu, GTK+ Version
3.24.38, cairo version 1.17.8) of 2023-09-15 built on localhost
Repository revision: 8a29da91bdcbffe2d7a67f04e235cdf238bd4be8
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101008
System Description: Gentoo Linux
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
next reply other threads:[~2023-09-18 8:38 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-09-18 8:38 Ihor Radchenko [this message]
2023-09-18 11:21 ` bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup Eli Zaretskii
2023-09-18 15:13 ` Michael Albinus
2023-09-19 10:12 ` Ihor Radchenko
2023-09-19 10:58 ` Ihor Radchenko
2023-09-19 12:11 ` Eli Zaretskii
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87cyyfkh9n.fsf@localhost \
--to=yantar92@posteo.net \
--cc=66067@debbugs.gnu.org \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.