[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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

On 01/04/13 18:29, Eric Blake wrote:
Based on a suggestion by John Ferlan:

* 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><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 @@
+        <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>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 :) ).


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]