Received-SPF: pass (google.com: domain of linux-kernel+bounces-68237-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
From: Jani Nikula <jani.nikula@intel.com>
To: Vegard Nossum <vegard.nossum@oracle.com>, Greg Kroah-Hartman
 <gregkh@linuxfoundation.org>
Cc: corbet@lwn.net, workflows@vger.kernel.org, linux-doc@vger.kernel.org,
 linux-kernel@vger.kernel.org, security@kernel.org, Kees Cook
 <keescook@chromium.org>, Sasha Levin <sashal@kernel.org>, Lee Jones
 <lee@kernel.org>
Subject: Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process
In-Reply-To: <26b25204-9829-44a8-9836-1ce1c8725586@oracle.com>
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
References: <2024021430-blanching-spotter-c7c8@gregkh>
 <00057b93-b5fc-4536-b13d-cd3b6cead5b1@oracle.com>
 <2024021530-plank-cornmeal-90eb@gregkh>
 <26b25204-9829-44a8-9836-1ce1c8725586@oracle.com>
Date: Fri, 16 Feb 2024 10:28:39 +0200
Message-ID: <87v86o4xu0.fsf@intel.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain

On Thu, 15 Feb 2024, Vegard Nossum <vegard.nossum@oracle.com> wrote:
> On 15/02/2024 12:50, Greg Kroah-Hartman wrote:
>> On Wed, Feb 14, 2024 at 09:37:31AM +0100, Vegard Nossum wrote:
>>> Document titles should have ==== above them as well, and then you would
>>> need to shift all the other headings in this document (i.e. all the ---
>>> should become ===).
>>>
>>> Info here: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation
>> 
>> Really?  I copied this directly from
>> Documentation/process/security-bugs.rst which is in the format that I
>> used here.  Which one is incorrect, I'm confused.
>
> Documentation/ currently has a mix of both formats and they both work,
> but the guidelines linked above is the gold standard and what we should
> aim for in new documents.
>
> The "correct" format would thus be:
>
> ====
> CVEs
> ====
>
> ...
>
> Process
> =======
>
> ...
>
> At least this is my understanding; I'm happy to be corrected (and in
> this case, we should also update the documentation).

rst basically allows any order of the heading underlines, and their
relative hierarchy is determined by how they show up in each document,
it's not specified by rst. However, it would be much easier for everyone
if all the kernel documents followed the same style.

BR,
Jani.


-- 
Jani Nikula, Intel