[libvirt] [PATCH] docs: add some more hacking tips

Peter Krempa pkrempa at redhat.com
Fri Jan 11 08:31:53 UTC 2013


On 01/04/13 18:29, Eric Blake wrote:
> Based on a suggestion by John Ferlan:
> https://www.redhat.com/archives/libvir-list/2013-January/msg00158.html
>
> * docs/hacking.html.in: Add some commit message instructions.
> Mention the ./run script.
> * HACKING: Regenerate.
> ---
>
> I don't know how to make docs/hacking2.xsl delay the line wrapping
> until after the '(3) ' prefix due to the <li> is inserted; as a
> result, there is a line longer than 80 columns.  Suggestions on
> improving the template are welcome.
>

Hm, I think of the 80 column boundary as a nice limit to start to think 
how to break the line. Today almost everybody has the fancy widescreen 
monitors so it's not that of an issue.

Having a few characters more in a line isn't in my opinion that bad as 
breaking a line due to that. (It bothers me the most mostl if a line has 
81 columns.). Well but rules are rules.

>   HACKING              | 26 ++++++++++++++++++++++----
>   docs/hacking.html.in | 19 ++++++++++++++++++-
>   2 files changed, 40 insertions(+), 5 deletions(-)
>

[...]

> diff --git a/docs/hacking.html.in b/docs/hacking.html.in
> index 40acdbb..17136f0 100644
> --- a/docs/hacking.html.in
> +++ b/docs/hacking.html.in
> @@ -59,6 +59,21 @@
>           version if needed though).</p>
>         </li>
>
> +      <li><p>In your commit message, make the summary line reasonably
> +          short (60 characters is typical), followed by a blank line,
> +          followed by any longer description of why your patch makes
> +          sense.  If the patch fixes a regression, and you know what
> +          commit introduced the problem, mentioning that is useful.
> +          If the patch resolves a bugzilla report, mentioning the URL
> +          of the bug number is useful; but also summarize the issue
> +          rather than making all readers follow the link.  You can use
> +          'git shortlog -30' to get an idea of typical summary lines.
> +          Libvirt does not currently attach any meaning to
> +          Signed-off-by: lines, so it is up to you if you want to
> +          include or omit them in the commit message.
> +        </p>
> +      </li>
> +
>         <li><p>Split large changes into a series of smaller patches,
>           self-contained if possible, with an explanation of each patch
>           and an explanation of how the sequence of patches fits
> @@ -110,7 +125,9 @@
>   <pre>
>     ./qemuxml2xmltest
>   </pre>
> -
> +        <p>There is also a <code>./run</code> script at the top level,
> +          to make it easier to run uninstalled programs, as well as to

"uninstalled" sounds to me as if I'd just remove them from my system. 
I'd change that to "programs that have not been installed in the system" 
or something with similar explanation

> +          wrap invocations of various tests under gdb or valgrind.</p>
>         </li>
>         <li>Update tests and/or documentation, particularly if you are adding
>           a new feature or changing the output of a program.</li>
>

ACK with the comment in the last hunk addressed (as the first one is 
just a meaningless rant :) ).

Peter




More information about the libvir-list mailing list