[PATCH] docs: move CODING_STYLE into the developer documentation

[PATCH] docs: move CODING_STYLE into the developer documentation

[Alex Bennée]

There is no particular reason to keep this on it's own in the root of
the tree. Move it into the rest of the fine developer manual and fixup
any links to it. The only tweak I've made is to fix the code-block
annotations to mention the language C.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/devel/index.rst                     | 1 +
 CODING_STYLE.rst => docs/devel/style.rst | 6 +++---
 README.rst                               | 4 +++-
 scripts/fix-multiline-comments.sh        | 2 +-
 4 files changed, 8 insertions(+), 5 deletions(-)
 rename CODING_STYLE.rst => docs/devel/style.rst (99%)

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 22854e334d..ae664da00c 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -14,6 +14,7 @@ Contents:
    :maxdepth: 2
 
    build-system
+   style
    kconfig
    testing
    fuzzing
diff --git a/CODING_STYLE.rst b/docs/devel/style.rst
similarity index 99%
rename from CODING_STYLE.rst
rename to docs/devel/style.rst
index 7bf4e39d48..8b0bdb3570 100644
--- a/CODING_STYLE.rst
+++ b/docs/devel/style.rst
@@ -641,7 +641,7 @@ trace-events style
 
 In trace-events files, use a '0x' prefix to specify hex numbers, as in:
 
-.. code-block::
+.. code-block:: c
 
     some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64
 
@@ -649,14 +649,14 @@ An exception is made for groups of numbers that are hexadecimal by
 convention and separated by the symbols '.', '/', ':', or ' ' (such as
 PCI bus id):
 
-.. code-block::
+.. code-block:: c
 
     another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x"
 
 However, you can use '0x' for such groups if you want. Anyway, be sure that
 it is obvious that numbers are in hex, ex.:
 
-.. code-block::
+.. code-block:: c
 
     data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x"
 
diff --git a/README.rst b/README.rst
index ce39d89077..f5d41e59b1 100644
--- a/README.rst
+++ b/README.rst
@@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
 format-patch' and/or 'git send-email' to format & send the mail to the
 qemu-devel@nongnu.org mailing list. All patches submitted must contain
 a 'Signed-off-by' line from the author. Patches should follow the
-guidelines set out in the CODING_STYLE.rst file.
+guidelines set out in the `style section
+<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
+the Developers Guide.
 
 Additional information on submitting patches can be found online via
 the QEMU website
diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh
index 93f9b10669..c15a041272 100755
--- a/scripts/fix-multiline-comments.sh
+++ b/scripts/fix-multiline-comments.sh
@@ -1,6 +1,6 @@
 #! /bin/sh
 #
-# Fix multiline comments to match CODING_STYLE
+# Fix multiline comments to match docs/devel/style.rst
 #
 # Copyright (C) 2018 Red Hat, Inc.
 #
-- 
2.20.1

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Claudio Fontana]

On 2/23/21 10:59 AM, Alex Bennée wrote:
> There is no particular reason to keep this on it's own in the root of
> the tree. Move it into the rest of the fine developer manual and fixup
> any links to it. The only tweak I've made is to fix the code-block
> annotations to mention the language C.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

Reviewed-by: Claudio Fontana <cfontana@suse.de>

Are there pointers in wiki.qemu.org that need updating?


> ---
>  docs/devel/index.rst                     | 1 +
>  CODING_STYLE.rst => docs/devel/style.rst | 6 +++---
>  README.rst                               | 4 +++-
>  scripts/fix-multiline-comments.sh        | 2 +-
>  4 files changed, 8 insertions(+), 5 deletions(-)
>  rename CODING_STYLE.rst => docs/devel/style.rst (99%)
> 
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index 22854e334d..ae664da00c 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -14,6 +14,7 @@ Contents:
>     :maxdepth: 2
>  
>     build-system
> +   style
>     kconfig
>     testing
>     fuzzing
> diff --git a/CODING_STYLE.rst b/docs/devel/style.rst
> similarity index 99%
> rename from CODING_STYLE.rst
> rename to docs/devel/style.rst
> index 7bf4e39d48..8b0bdb3570 100644
> --- a/CODING_STYLE.rst
> +++ b/docs/devel/style.rst
> @@ -641,7 +641,7 @@ trace-events style
>  
>  In trace-events files, use a '0x' prefix to specify hex numbers, as in:
>  
> -.. code-block::
> +.. code-block:: c
>  
>      some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64
>  
> @@ -649,14 +649,14 @@ An exception is made for groups of numbers that are hexadecimal by
>  convention and separated by the symbols '.', '/', ':', or ' ' (such as
>  PCI bus id):
>  
> -.. code-block::
> +.. code-block:: c
>  
>      another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x"
>  
>  However, you can use '0x' for such groups if you want. Anyway, be sure that
>  it is obvious that numbers are in hex, ex.:
>  
> -.. code-block::
> +.. code-block:: c
>  
>      data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x"
>  
> diff --git a/README.rst b/README.rst
> index ce39d89077..f5d41e59b1 100644
> --- a/README.rst
> +++ b/README.rst
> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
>  format-patch' and/or 'git send-email' to format & send the mail to the
>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
>  a 'Signed-off-by' line from the author. Patches should follow the
> -guidelines set out in the CODING_STYLE.rst file.
> +guidelines set out in the `style section
> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
> +the Developers Guide.
>  
>  Additional information on submitting patches can be found online via
>  the QEMU website
> diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh
> index 93f9b10669..c15a041272 100755
> --- a/scripts/fix-multiline-comments.sh
> +++ b/scripts/fix-multiline-comments.sh
> @@ -1,6 +1,6 @@
>  #! /bin/sh
>  #
> -# Fix multiline comments to match CODING_STYLE
> +# Fix multiline comments to match docs/devel/style.rst
>  #
>  # Copyright (C) 2018 Red Hat, Inc.
>  #
> 

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Peter Maydell]

On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> There is no particular reason to keep this on it's own in the root of
> the tree. Move it into the rest of the fine developer manual and fixup
> any links to it. The only tweak I've made is to fix the code-block
> annotations to mention the language C.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
> diff --git a/README.rst b/README.rst
> index ce39d89077..f5d41e59b1 100644
> --- a/README.rst
> +++ b/README.rst
> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
>  format-patch' and/or 'git send-email' to format & send the mail to the
>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
>  a 'Signed-off-by' line from the author. Patches should follow the
> -guidelines set out in the CODING_STYLE.rst file.
> +guidelines set out in the `style section
> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
> +the Developers Guide.

This is the first instance of a qemu.readthedocs.io URL in the
tree. Do we really want to have our references to our documentation
be to a third party website ?

thanks
-- PMM

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Philippe Mathieu-Daudé]

On 2/23/21 12:07 PM, Peter Maydell wrote:
> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
>>
>> There is no particular reason to keep this on it's own in the root of
>> the tree. Move it into the rest of the fine developer manual and fixup
>> any links to it. The only tweak I've made is to fix the code-block
>> annotations to mention the language C.
>>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> ---
>> diff --git a/README.rst b/README.rst
>> index ce39d89077..f5d41e59b1 100644
>> --- a/README.rst
>> +++ b/README.rst
>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
>>  format-patch' and/or 'git send-email' to format & send the mail to the
>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
>>  a 'Signed-off-by' line from the author. Patches should follow the
>> -guidelines set out in the CODING_STYLE.rst file.
>> +guidelines set out in the `style section
>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
>> +the Developers Guide.
> 
> This is the first instance of a qemu.readthedocs.io URL in the
> tree. Do we really want to have our references to our documentation
> be to a third party website ?

We can use https://www.qemu.org/docs/master/devel/style.html:

$ curl https://www.qemu.org/docs/master/devel/style.html
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>302 Found</title>
</head><body>
<h1>Found</h1>
<p>The document has moved <a
href="https://qemu.readthedocs.io/en/latest/devel/style.html">here</a>.</p>
</body></html>

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Philippe Mathieu-Daudé]

On 2/23/21 12:29 PM, Philippe Mathieu-Daudé wrote:
> On 2/23/21 12:07 PM, Peter Maydell wrote:
>> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
>>>
>>> There is no particular reason to keep this on it's own in the root of
>>> the tree. Move it into the rest of the fine developer manual and fixup
>>> any links to it. The only tweak I've made is to fix the code-block
>>> annotations to mention the language C.
>>>
>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>> ---
>>> diff --git a/README.rst b/README.rst
>>> index ce39d89077..f5d41e59b1 100644
>>> --- a/README.rst
>>> +++ b/README.rst
>>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
>>>  format-patch' and/or 'git send-email' to format & send the mail to the
>>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
>>>  a 'Signed-off-by' line from the author. Patches should follow the
>>> -guidelines set out in the CODING_STYLE.rst file.
>>> +guidelines set out in the `style section
>>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
>>> +the Developers Guide.
>>
>> This is the first instance of a qemu.readthedocs.io URL in the
>> tree. Do we really want to have our references to our documentation
>> be to a third party website ?
> 
> We can use https://www.qemu.org/docs/master/devel/style.html:
> 
> $ curl https://www.qemu.org/docs/master/devel/style.html
> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
> <html><head>
> <title>302 Found</title>
> </head><body>
> <h1>Found</h1>
> <p>The document has moved <a
> href="https://qemu.readthedocs.io/en/latest/devel/style.html">here</a>.</p>
> </body></html>

Or even better since we have a job pushing to Gitlab pages
accessible on https://qemu-project.gitlab.io/qemu/:

https://qemu-project.gitlab.io/qemu/devel/style.html

Maybe the https://www.qemu.org/docs/ redirect should
go to gitlab page now?

Phil.

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
>>
>> There is no particular reason to keep this on it's own in the root of
>> the tree. Move it into the rest of the fine developer manual and fixup
>> any links to it. The only tweak I've made is to fix the code-block
>> annotations to mention the language C.
>>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> ---
>> diff --git a/README.rst b/README.rst
>> index ce39d89077..f5d41e59b1 100644
>> --- a/README.rst
>> +++ b/README.rst
>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
>>  format-patch' and/or 'git send-email' to format & send the mail to the
>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
>>  a 'Signed-off-by' line from the author. Patches should follow the
>> -guidelines set out in the CODING_STYLE.rst file.
>> +guidelines set out in the `style section
>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
>> +the Developers Guide.
>
> This is the first instance of a qemu.readthedocs.io URL in the
> tree. Do we really want to have our references to our documentation
> be to a third party website ?

Well I browsed to:

  https://www.qemu.org/docs/master/

which re-directed me to the readthedocs URL. However it looks like:

  https://www.qemu.org/docs/master/devel/index.html

DTRT so I can fix that.

>
> thanks
> -- PMM


-- 
Alex Bennée

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Alex Bennée]

Philippe Mathieu-Daudé <philmd@redhat.com> writes:

> On 2/23/21 12:29 PM, Philippe Mathieu-Daudé wrote:
>> On 2/23/21 12:07 PM, Peter Maydell wrote:
>>> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
>>>>
>>>> There is no particular reason to keep this on it's own in the root of
>>>> the tree. Move it into the rest of the fine developer manual and fixup
>>>> any links to it. The only tweak I've made is to fix the code-block
>>>> annotations to mention the language C.
>>>>
>>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>>> ---
>>>> diff --git a/README.rst b/README.rst
>>>> index ce39d89077..f5d41e59b1 100644
>>>> --- a/README.rst
>>>> +++ b/README.rst
>>>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
>>>>  format-patch' and/or 'git send-email' to format & send the mail to the
>>>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
>>>>  a 'Signed-off-by' line from the author. Patches should follow the
>>>> -guidelines set out in the CODING_STYLE.rst file.
>>>> +guidelines set out in the `style section
>>>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
>>>> +the Developers Guide.
>>>
>>> This is the first instance of a qemu.readthedocs.io URL in the
>>> tree. Do we really want to have our references to our documentation
>>> be to a third party website ?
>> 
>> We can use https://www.qemu.org/docs/master/devel/style.html:
>> 
>> $ curl https://www.qemu.org/docs/master/devel/style.html
>> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
>> <html><head>
>> <title>302 Found</title>
>> </head><body>
>> <h1>Found</h1>
>> <p>The document has moved <a
>> href="https://qemu.readthedocs.io/en/latest/devel/style.html">here</a>.</p>
>> </body></html>

I think if we treat the qemu.org domain as being the canonical URL and
then let it redirect where it wants. 

> Or even better since we have a job pushing to Gitlab pages
> accessible on https://qemu-project.gitlab.io/qemu/:
>
> https://qemu-project.gitlab.io/qemu/devel/style.html
>
> Maybe the https://www.qemu.org/docs/ redirect should
> go to gitlab page now?

It could do either, I think the result is exactly the same.

>
> Phil.


-- 
Alex Bennée

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Alex Bennée]

Claudio Fontana <cfontana@suse.de> writes:

> On 2/23/21 10:59 AM, Alex Bennée wrote:
>> There is no particular reason to keep this on it's own in the root of
>> the tree. Move it into the rest of the fine developer manual and fixup
>> any links to it. The only tweak I've made is to fix the code-block
>> annotations to mention the language C.
>> 
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> Reviewed-by: Claudio Fontana <cfontana@suse.de>
>
> Are there pointers in wiki.qemu.org that need updating?

The Contribute/StartHere wiki page redirects to Contribute but I guess
it would be better to move some of that content either to the devel
manual or the website.

>
>
>> ---
>>  docs/devel/index.rst                     | 1 +
>>  CODING_STYLE.rst => docs/devel/style.rst | 6 +++---
>>  README.rst                               | 4 +++-
>>  scripts/fix-multiline-comments.sh        | 2 +-
>>  4 files changed, 8 insertions(+), 5 deletions(-)
>>  rename CODING_STYLE.rst => docs/devel/style.rst (99%)
>> 
>> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
>> index 22854e334d..ae664da00c 100644
>> --- a/docs/devel/index.rst
>> +++ b/docs/devel/index.rst
>> @@ -14,6 +14,7 @@ Contents:
>>     :maxdepth: 2
>>  
>>     build-system
>> +   style
>>     kconfig
>>     testing
>>     fuzzing
>> diff --git a/CODING_STYLE.rst b/docs/devel/style.rst
>> similarity index 99%
>> rename from CODING_STYLE.rst
>> rename to docs/devel/style.rst
>> index 7bf4e39d48..8b0bdb3570 100644
>> --- a/CODING_STYLE.rst
>> +++ b/docs/devel/style.rst
>> @@ -641,7 +641,7 @@ trace-events style
>>  
>>  In trace-events files, use a '0x' prefix to specify hex numbers, as in:
>>  
>> -.. code-block::
>> +.. code-block:: c
>>  
>>      some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64
>>  
>> @@ -649,14 +649,14 @@ An exception is made for groups of numbers that are hexadecimal by
>>  convention and separated by the symbols '.', '/', ':', or ' ' (such as
>>  PCI bus id):
>>  
>> -.. code-block::
>> +.. code-block:: c
>>  
>>      another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x"
>>  
>>  However, you can use '0x' for such groups if you want. Anyway, be sure that
>>  it is obvious that numbers are in hex, ex.:
>>  
>> -.. code-block::
>> +.. code-block:: c
>>  
>>      data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x"
>>  
>> diff --git a/README.rst b/README.rst
>> index ce39d89077..f5d41e59b1 100644
>> --- a/README.rst
>> +++ b/README.rst
>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
>>  format-patch' and/or 'git send-email' to format & send the mail to the
>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
>>  a 'Signed-off-by' line from the author. Patches should follow the
>> -guidelines set out in the CODING_STYLE.rst file.
>> +guidelines set out in the `style section
>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
>> +the Developers Guide.
>>  
>>  Additional information on submitting patches can be found online via
>>  the QEMU website
>> diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh
>> index 93f9b10669..c15a041272 100755
>> --- a/scripts/fix-multiline-comments.sh
>> +++ b/scripts/fix-multiline-comments.sh
>> @@ -1,6 +1,6 @@
>>  #! /bin/sh
>>  #
>> -# Fix multiline comments to match CODING_STYLE
>> +# Fix multiline comments to match docs/devel/style.rst
>>  #
>>  # Copyright (C) 2018 Red Hat, Inc.
>>  #
>> 


-- 
Alex Bennée

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 2931 bytes --]

On Tue, Feb 23, 2021 at 01:37:45PM +0000, Alex Bennée wrote:
> 
> Philippe Mathieu-Daudé <philmd@redhat.com> writes:
> 
> > On 2/23/21 12:29 PM, Philippe Mathieu-Daudé wrote:
> >> On 2/23/21 12:07 PM, Peter Maydell wrote:
> >>> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
> >>>>
> >>>> There is no particular reason to keep this on it's own in the root of
> >>>> the tree. Move it into the rest of the fine developer manual and fixup
> >>>> any links to it. The only tweak I've made is to fix the code-block
> >>>> annotations to mention the language C.
> >>>>
> >>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >>>> ---
> >>>> diff --git a/README.rst b/README.rst
> >>>> index ce39d89077..f5d41e59b1 100644
> >>>> --- a/README.rst
> >>>> +++ b/README.rst
> >>>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
> >>>>  format-patch' and/or 'git send-email' to format & send the mail to the
> >>>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
> >>>>  a 'Signed-off-by' line from the author. Patches should follow the
> >>>> -guidelines set out in the CODING_STYLE.rst file.
> >>>> +guidelines set out in the `style section
> >>>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
> >>>> +the Developers Guide.
> >>>
> >>> This is the first instance of a qemu.readthedocs.io URL in the
> >>> tree. Do we really want to have our references to our documentation
> >>> be to a third party website ?
> >> 
> >> We can use https://www.qemu.org/docs/master/devel/style.html:
> >> 
> >> $ curl https://www.qemu.org/docs/master/devel/style.html
> >> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
> >> <html><head>
> >> <title>302 Found</title>
> >> </head><body>
> >> <h1>Found</h1>
> >> <p>The document has moved <a
> >> href="https://qemu.readthedocs.io/en/latest/devel/style.html">here</a>.</p>
> >> </body></html>
> 
> I think if we treat the qemu.org domain as being the canonical URL and
> then let it redirect where it wants. 

Yes, let's treat qemu.org as the canonical domain so we have the ability
to change locations easily later.

> > Or even better since we have a job pushing to Gitlab pages
> > accessible on https://qemu-project.gitlab.io/qemu/:
> >
> > https://qemu-project.gitlab.io/qemu/devel/style.html
> >
> > Maybe the https://www.qemu.org/docs/ redirect should
> > go to gitlab page now?
> 
> It could do either, I think the result is exactly the same.

Standarizing project infrastructure on GitLab CI seems good to me. That
way developers will be able to reuse their CI knowledge and won't have
to learn other systems (like readthedocs).

However, I don't see .gitlab-ci.yml directives that build the docs and
publish a static page yet. Is anyone volunteering to do this? (It can be
done as a separate step from this patch.)

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Daniel P. Berrangé]

On Wed, Feb 24, 2021 at 12:15:05PM +0000, Stefan Hajnoczi wrote:
> On Tue, Feb 23, 2021 at 01:37:45PM +0000, Alex Bennée wrote:
> > 
> > Philippe Mathieu-Daudé <philmd@redhat.com> writes:
> > 
> > > On 2/23/21 12:29 PM, Philippe Mathieu-Daudé wrote:
> > >> On 2/23/21 12:07 PM, Peter Maydell wrote:
> > >>> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
> > >>>>
> > >>>> There is no particular reason to keep this on it's own in the root of
> > >>>> the tree. Move it into the rest of the fine developer manual and fixup
> > >>>> any links to it. The only tweak I've made is to fix the code-block
> > >>>> annotations to mention the language C.
> > >>>>
> > >>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> > >>>> ---
> > >>>> diff --git a/README.rst b/README.rst
> > >>>> index ce39d89077..f5d41e59b1 100644
> > >>>> --- a/README.rst
> > >>>> +++ b/README.rst
> > >>>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
> > >>>>  format-patch' and/or 'git send-email' to format & send the mail to the
> > >>>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
> > >>>>  a 'Signed-off-by' line from the author. Patches should follow the
> > >>>> -guidelines set out in the CODING_STYLE.rst file.
> > >>>> +guidelines set out in the `style section
> > >>>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
> > >>>> +the Developers Guide.
> > >>>
> > >>> This is the first instance of a qemu.readthedocs.io URL in the
> > >>> tree. Do we really want to have our references to our documentation
> > >>> be to a third party website ?
> > >> 
> > >> We can use https://www.qemu.org/docs/master/devel/style.html:
> > >> 
> > >> $ curl https://www.qemu.org/docs/master/devel/style.html
> > >> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
> > >> <html><head>
> > >> <title>302 Found</title>
> > >> </head><body>
> > >> <h1>Found</h1>
> > >> <p>The document has moved <a
> > >> href="https://qemu.readthedocs.io/en/latest/devel/style.html">here</a>.</p>
> > >> </body></html>
> > 
> > I think if we treat the qemu.org domain as being the canonical URL and
> > then let it redirect where it wants. 
> 
> Yes, let's treat qemu.org as the canonical domain so we have the ability
> to change locations easily later.
> 
> > > Or even better since we have a job pushing to Gitlab pages
> > > accessible on https://qemu-project.gitlab.io/qemu/:
> > >
> > > https://qemu-project.gitlab.io/qemu/devel/style.html
> > >
> > > Maybe the https://www.qemu.org/docs/ redirect should
> > > go to gitlab page now?
> > 
> > It could do either, I think the result is exactly the same.
> 
> Standarizing project infrastructure on GitLab CI seems good to me. That
> way developers will be able to reuse their CI knowledge and won't have
> to learn other systems (like readthedocs).
> 
> However, I don't see .gitlab-ci.yml directives that build the docs and
> publish a static page yet. Is anyone volunteering to do this? (It can be
> done as a separate step from this patch.)

The very last job (called 'pages') in .gitlab-ci.yml does this.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 3650 bytes --]

On Wed, Feb 24, 2021 at 12:19:25PM +0000, Daniel P. Berrangé wrote:
> On Wed, Feb 24, 2021 at 12:15:05PM +0000, Stefan Hajnoczi wrote:
> > On Tue, Feb 23, 2021 at 01:37:45PM +0000, Alex Bennée wrote:
> > > 
> > > Philippe Mathieu-Daudé <philmd@redhat.com> writes:
> > > 
> > > > On 2/23/21 12:29 PM, Philippe Mathieu-Daudé wrote:
> > > >> On 2/23/21 12:07 PM, Peter Maydell wrote:
> > > >>> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
> > > >>>>
> > > >>>> There is no particular reason to keep this on it's own in the root of
> > > >>>> the tree. Move it into the rest of the fine developer manual and fixup
> > > >>>> any links to it. The only tweak I've made is to fix the code-block
> > > >>>> annotations to mention the language C.
> > > >>>>
> > > >>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> > > >>>> ---
> > > >>>> diff --git a/README.rst b/README.rst
> > > >>>> index ce39d89077..f5d41e59b1 100644
> > > >>>> --- a/README.rst
> > > >>>> +++ b/README.rst
> > > >>>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
> > > >>>>  format-patch' and/or 'git send-email' to format & send the mail to the
> > > >>>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
> > > >>>>  a 'Signed-off-by' line from the author. Patches should follow the
> > > >>>> -guidelines set out in the CODING_STYLE.rst file.
> > > >>>> +guidelines set out in the `style section
> > > >>>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
> > > >>>> +the Developers Guide.
> > > >>>
> > > >>> This is the first instance of a qemu.readthedocs.io URL in the
> > > >>> tree. Do we really want to have our references to our documentation
> > > >>> be to a third party website ?
> > > >> 
> > > >> We can use https://www.qemu.org/docs/master/devel/style.html:
> > > >> 
> > > >> $ curl https://www.qemu.org/docs/master/devel/style.html
> > > >> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
> > > >> <html><head>
> > > >> <title>302 Found</title>
> > > >> </head><body>
> > > >> <h1>Found</h1>
> > > >> <p>The document has moved <a
> > > >> href="https://qemu.readthedocs.io/en/latest/devel/style.html">here</a>.</p>
> > > >> </body></html>
> > > 
> > > I think if we treat the qemu.org domain as being the canonical URL and
> > > then let it redirect where it wants. 
> > 
> > Yes, let's treat qemu.org as the canonical domain so we have the ability
> > to change locations easily later.
> > 
> > > > Or even better since we have a job pushing to Gitlab pages
> > > > accessible on https://qemu-project.gitlab.io/qemu/:
> > > >
> > > > https://qemu-project.gitlab.io/qemu/devel/style.html
> > > >
> > > > Maybe the https://www.qemu.org/docs/ redirect should
> > > > go to gitlab page now?
> > > 
> > > It could do either, I think the result is exactly the same.
> > 
> > Standarizing project infrastructure on GitLab CI seems good to me. That
> > way developers will be able to reuse their CI knowledge and won't have
> > to learn other systems (like readthedocs).
> > 
> > However, I don't see .gitlab-ci.yml directives that build the docs and
> > publish a static page yet. Is anyone volunteering to do this? (It can be
> > done as a separate step from this patch.)
> 
> The very last job (called 'pages') in .gitlab-ci.yml does this.

Awesome! I have updated the qemu.org HTTP redirect to GitLab:

  https://qemu.org/docs/master/

If anyone wants to discuss RTD vs GitLab docs hosting more, please go
ahead. We can change the redirect again in the future, if necessary.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Daniel P. Berrangé]

On Wed, Feb 24, 2021 at 03:25:41PM +0000, Stefan Hajnoczi wrote:
> On Wed, Feb 24, 2021 at 12:19:25PM +0000, Daniel P. Berrangé wrote:
> > On Wed, Feb 24, 2021 at 12:15:05PM +0000, Stefan Hajnoczi wrote:
> > > On Tue, Feb 23, 2021 at 01:37:45PM +0000, Alex Bennée wrote:
> > > > 
> > > > Philippe Mathieu-Daudé <philmd@redhat.com> writes:
> > > > > Or even better since we have a job pushing to Gitlab pages
> > > > > accessible on https://qemu-project.gitlab.io/qemu/:
> > > > >
> > > > > https://qemu-project.gitlab.io/qemu/devel/style.html
> > > > >
> > > > > Maybe the https://www.qemu.org/docs/ redirect should
> > > > > go to gitlab page now?
> > > > 
> > > > It could do either, I think the result is exactly the same.
> > > 
> > > Standarizing project infrastructure on GitLab CI seems good to me. That
> > > way developers will be able to reuse their CI knowledge and won't have
> > > to learn other systems (like readthedocs).
> > > 
> > > However, I don't see .gitlab-ci.yml directives that build the docs and
> > > publish a static page yet. Is anyone volunteering to do this? (It can be
> > > done as a separate step from this patch.)
> > 
> > The very last job (called 'pages') in .gitlab-ci.yml does this.
> 
> Awesome! I have updated the qemu.org HTTP redirect to GitLab:
> 
>   https://qemu.org/docs/master/
> 
> If anyone wants to discuss RTD vs GitLab docs hosting more, please go
> ahead. We can change the redirect again in the future, if necessary.

The downside with using a HTTP redirect is that user's still see the
particular hosting choice. So they are liable to bookmark these
links which will  break if we move again.

Paolo had proposed a patch to rsync the CI content directly onto
qemu.org:

  https://lists.gnu.org/archive/html/qemu-devel/2021-01/msg04629.html

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH] docs: move CODING_STYLE into the developer documentation

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 2021 bytes --]

On Wed, Feb 24, 2021 at 03:33:41PM +0000, Daniel P. Berrangé wrote:
> On Wed, Feb 24, 2021 at 03:25:41PM +0000, Stefan Hajnoczi wrote:
> > On Wed, Feb 24, 2021 at 12:19:25PM +0000, Daniel P. Berrangé wrote:
> > > On Wed, Feb 24, 2021 at 12:15:05PM +0000, Stefan Hajnoczi wrote:
> > > > On Tue, Feb 23, 2021 at 01:37:45PM +0000, Alex Bennée wrote:
> > > > > 
> > > > > Philippe Mathieu-Daudé <philmd@redhat.com> writes:
> > > > > > Or even better since we have a job pushing to Gitlab pages
> > > > > > accessible on https://qemu-project.gitlab.io/qemu/:
> > > > > >
> > > > > > https://qemu-project.gitlab.io/qemu/devel/style.html
> > > > > >
> > > > > > Maybe the https://www.qemu.org/docs/ redirect should
> > > > > > go to gitlab page now?
> > > > > 
> > > > > It could do either, I think the result is exactly the same.
> > > > 
> > > > Standarizing project infrastructure on GitLab CI seems good to me. That
> > > > way developers will be able to reuse their CI knowledge and won't have
> > > > to learn other systems (like readthedocs).
> > > > 
> > > > However, I don't see .gitlab-ci.yml directives that build the docs and
> > > > publish a static page yet. Is anyone volunteering to do this? (It can be
> > > > done as a separate step from this patch.)
> > > 
> > > The very last job (called 'pages') in .gitlab-ci.yml does this.
> > 
> > Awesome! I have updated the qemu.org HTTP redirect to GitLab:
> > 
> >   https://qemu.org/docs/master/
> > 
> > If anyone wants to discuss RTD vs GitLab docs hosting more, please go
> > ahead. We can change the redirect again in the future, if necessary.
> 
> The downside with using a HTTP redirect is that user's still see the
> particular hosting choice. So they are liable to bookmark these
> links which will  break if we move again.
> 
> Paolo had proposed a patch to rsync the CI content directly onto
> qemu.org:
> 
>   https://lists.gnu.org/archive/html/qemu-devel/2021-01/msg04629.html

That sounds good too.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Files without license statement

[Stefan Weil via]

Hi Paolo,

I just noticed that scripts/fix-multiline-comments.sh has a copyright 
statement, but no license statement. Should that be fixed?

It looks like there exist more files with the same problem (if it is a 
problem), for example docs/devel/loads-stores.rst (written by Peter).

LICENSE says that "Source files with no licensing information are 
released under the GNU General Public License [...]". Does that include 
shell and Python scripts, documentation and other files which might not 
be regarded as "source files"? Or should that be updated to "Any files 
with no licensing information [...]" which would also include files 
which have neither a copyright nor a license statement?

Kind regards
Stefan W.