Minor updates to the git tutorial and our commit message policies.

1 files changed, 12 insertions, 2 deletions

diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod
index cc303b1b57..7eae645c51 100644
--- a/pod/perlrepository.pod
+++ b/pod/perlrepository.pod
@@ -233,8 +233,9 @@ a single atomic unit, run this command:
    % git commit -a
 
 (That C<-a> tells git to add every file you've changed to this commit.
-If you want to commit some, but not all of your changes, have a look
-at the documentation for C<git add>.)
+New files aren't automatically added to your commit when you use C<commit
+-a> If you want to add files or to commit some, but not all of your
+changes, have a look at the documentation for C<git add>.)
 
 Git will start up your favorite text editor, so that you can craft a
 commit message for your change. See L</Commit message> below for more
@@ -459,6 +460,15 @@ month or next year.
 
 =back
 
+A commit message isn't intended to take the place of comments in your
+code.  Commit messages should describe the change you made, while code
+comments should describe the current state of the code.  If you've
+just implemented a new feature, complete with doc, tests and well-
+commented code, a brief commit message will often suffice.  If, however,
+you've just a single character deep in the parser or lexer, you might
+need to write a small novel to ensure that future readers understand
+what you did and why you did it.
+
 =item Comments, Comments, Comments
 
 Be sure to adequately comment your code.  While commenting every line