Subject: bug#66067: closed (Re: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup)

From: [email-masked] (GNU bug Tracking System)
Date: Mon, 18 Sep 2023 11:23:02 +0000

Your bug report

#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
66067: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=66067
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
From: Eli Zaretskii <[email-masked]>
To: Ihor Radchenko <[email-masked]>
Cc: [email-masked]
Date: Mon, 18 Sep 2023 14:21:54 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Ihor Radchenko <[email-masked]>
> Date: Mon, 18 Sep 2023 08:38:44 +0000
> 
> 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.

That's because "it depends": the entries should be arranged in the
order of importance, if possible.  Usually, the importance order is
not very clear, with rare exceptions, so the order is basically
arbitrary.

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

I'm surprised it wasn't clear, but I added an explicit "before".

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

We support both styles, and there are strong feelings in both camps.
'Nough said.

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

There is no such convention.  The r_is_ a convention for this in Lisp
doc strings, and it is described in the ELisp manual.

Closing.

Subject: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
From: Ihor Radchenko <[email-masked]>
To: [email-masked]
Date: Mon, 18 Sep 2023 08:38:44 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

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>