Re: [PATCH bpf-next] docs/bpf: Document how to run CI without patch submission

[Akira Yokosawa <akiyks@gmail.com>]

On Wed, 16 Nov 2022 17:20:19 +0000, Daniel Müller wrote:
> Hi Akira,
> 
> On Wed, Nov 16, 2022 at 07:01:17PM +0900, Akira Yokosawa wrote:
>> I know this has already been applied, but am seeing new warning msgs
>> from "make htmldocs" due to this change. Please see inline comment
>> below.
>>
>> On Mon, 14 Nov 2022 21:15:01 +0000, Daniel Müller wrote:
>>> This change documents the process for running the BPF CI before
>>> submitting a patch to the upstream mailing list, similar to what happens
>>> if a patch is send to bpf@vger.kernel.org: it builds kernel and
>>> selftests and runs the latter on different architecture (but it notably
>>> does not cover stylistic checks such as cover letter verification).
>>> Running BPF CI this way can help achieve better test coverage ahead of
>>> patch submission than merely running locally (say, using
>>> tools/testing/selftests/bpf/vmtest.sh), as additional architectures may
>>> be covered as well.
>>>
>>> Signed-off-by: Daniel Müller <deso@posteo.net>
>>> ---
>>>  Documentation/bpf/bpf_devel_QA.rst | 24 ++++++++++++++++++++++++
>>>  1 file changed, 24 insertions(+)
>>>
>>> diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst
>>> index 761474..08572c7 100644
>>> --- a/Documentation/bpf/bpf_devel_QA.rst
>>> +++ b/Documentation/bpf/bpf_devel_QA.rst
>>> @@ -44,6 +44,30 @@ is a guarantee that the reported issue will be overlooked.**
>>>  Submitting patches
>>>  ==================
>>>  
>>> +Q: How do I run BPF CI on my changes before sending them out for review?
>>> +------------------------------------------------------------------------
>>> +A: BPF CI is GitHub based and hosted at https://github.com/kernel-patches/bpf.
>>> +While GitHub also provides a CLI that can be used to accomplish the same
>>> +results, here we focus on the UI based workflow.
>>> +
>>> +The following steps lay out how to start a CI run for your patches:
>>
>> Lack of a blank line here results in warning msgs from "make htmldocs":
>>
>> /linux/Documentation/bpf/bpf_devel_QA.rst:55: ERROR: Unexpected indentation.
>> /linux/Documentation/bpf/bpf_devel_QA.rst:56: WARNING: Block quote ends without a blank line; unexpected unindent.
>>
>> Can you please fix it?
>>
>> For your reference, here is a link to reST documentation on bullet lists:
>>
>>     https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
>>
>>         Thanks, Akira
> 
> Thanks for pointing that out. I had not found any references to this rst file
> being included in automated doc generation. Will fix it up.

JFYI,

bpf_devel_QA is listed under the toctree directive in Documentation/bpf/faq.rst.

If you failed to enlist a new .rst file in a toctree somewhere, you would see
a complaint from "make htmldocs", in this case:

  Documentation/bpf/bpf_devel_QA.rst: WARNING: document isn't included in any toctree

        Thanks, Akira

> 
> Daniel