[nemiver] Update HACKING documentation

[Dodji Seketeli <dodji src gnome org>]

commit be981b02eb6c0d512592ca7d76eb56d63a4e4a2c
Author: Dodji Seketeli <dodji seketeli org>
Date:   Sun Apr 10 13:05:51 2011 +0200

    Update HACKING documentation
    
    	* README: Add space between each paragraph and its header.
    	* README.git-commit-messages.txt: Renamed
    	git-commit-messages.README into this.  Re-flowed paragraphs.
    	* README.hacking.txt: New file.

 README                         |   15 ++++++++
 README.git-commit-messages.txt |   47 ++++++++++++++++++++++++
 README.hacking.txt             |   76 ++++++++++++++++++++++++++++++++++++++++
 git-commit-messages.README     |   33 -----------------
 4 files changed, 138 insertions(+), 33 deletions(-)
---
diff --git a/README b/README
index 31f1cfa..455b6c6 100644
--- a/README
+++ b/README
@@ -1,11 +1,13 @@
 About
 =====
+
 Nemiver is a project to write a standalone graphical debugger that integrates
 well in the GNOME desktop environment.
 It currently features a backend which uses the well known GNU Debugger gdb.
 
 General
 =======
+
 - In addition to the toolbar buttons, you can toggle breakpoints simply by
   clicking in the margin on the line you want to break on.
 - Hovering over a variable name for longer than 1 second should show its value
@@ -16,6 +18,7 @@ General
 
 Sessions
 ========
+
 Nemiver uses a sqlite database to store basic information about a debugging
 session so you can resume where you left off last time.  Whenever you start
 debugging, a new session is created for you automatically (unless you explicitly
@@ -31,6 +34,7 @@ To resume the last saved debugging session you can just type "nemiver --last".
 
 Source Directories
 ==================
+
 Some versions of the GDB debugger don't provide full pathname information for
 breakpoints, etc.  In this case, you may need to specify which directories to
 search for source files.  These can be specified by manually adding source
@@ -40,6 +44,7 @@ determine the absolute path of a file on its own.
 
 Extending Nemiver
 =================
+
 Nemiver is a bit more than just a simple GUI debugger.  It is actually a
 platform which can be extended with plugins and dynamically loaded modules.
 The libnemivercommon library provides the basic functionality for loading
@@ -54,11 +59,21 @@ other projects seeking to implement a debugger as a part of an IDE, for example.
 
 Automated Tests
 ===============
+
 Nemiver includes several automated unit tests which can be run with `make
 check`.  Because nemiver uses dynamically-loaded modules, however, these tests
 must be run after installing nemiver, otherwise they will not work.
 
 Reporting Bugs
 ==============
+
 If you've found a bug with Nemiver, we'd like to know about it.  Bugs are
 tracked in the GNOME Bugzilla bug tracker: http://bugzilla.gnome.org/
+
+Contact
+=======
+
+If you have any question related to nemiver, you can send an email to
+nemiver-list gnome org   If you have patches you would like to see
+included in the code base, you can send them to that same email
+address as well.
diff --git a/README.git-commit-messages.txt b/README.git-commit-messages.txt
new file mode 100644
index 0000000..1991324
--- /dev/null
+++ b/README.git-commit-messages.txt
@@ -0,0 +1,47 @@
+Git commit messages format
+==========================
+
+The principle of the git commit log is to document at least the
+*what*; in English.  That is redundant with the commit diff, yes.  But
+that redundancy does help in understanding the commit diff better.  If
+appropriate, the commit log can also document the *why*, but only if
+it does so by respecting the format of the commit log.  The reason why
+we are so strict about the format is that the commit log is later
+parsed by a tool to build a ChangeLog, which we want to stay compliant
+with the GNU ChangeLog format.
+
+So here is the format we are talking about.
+
+The first line of a git commit message should start at column 1, with
+no space. That line should be a short summary of the purpose of the
+commit.  If the commit relates to a bug filed into bugzilla, the line
+should begin with the bug number, followed by a white space; e.g:
+
+#<number-of-the-bug> This is a great commit
+
+The line in its entirety should not be longer than 50 characters.
+
+The next line should be an empty line, with no spaces.
+
+The subsequent lines should have the form of the Body of a GNU ChangeLog
+entry, i.e:
+
+	* file1.c (func1): Changed foo in this function.
+	(func2): Changed blah in that function
+	* file2.c (func_foo): Changed something here.
+
+Note that before the '*', there is a tab that is 8 spaces long.  Also
+note that right after the '*', there is a space.
+
+An exemple of commit message would be:
+
+~=~
+123456 Shorten compilation lines
+
+	* configure.ac: Shorten compilation lines by regrouping
+	PKG_CHECK_MODULES calls.
+	* tests/Makefile.am: Adjust this.
+~=~
+
+We encourage you to look at the existing commit logs or at the
+ChangeLog file for inspiration.
diff --git a/README.hacking.txt b/README.hacking.txt
new file mode 100644
index 0000000..8c99c63
--- /dev/null
+++ b/README.hacking.txt
@@ -0,0 +1,76 @@
+Prior to reading this, please make sure you have read the README file
+in the topmost directory.
+
+Getting the canonical source code
+=================================
+
+The source code of Nemiver is managed using the Git source control
+management system (http://git-scm.com).  If you want to hack on
+Nemiver, we advise you to learn about Git and then get the full
+development history of Nemiver by doing:
+
+    git clone git://git.gnome.org/git/nemiver nemiver.git
+
+Once that command completes, you will have the source code (as well as
+all the development history) in the directory nemiver.git.  Now you
+are ready to hack.
+
+Alternatively, you can also start hacking the source code from a
+source tarball that you would have downloaded from somewhere.  Both
+ways are just fine, technically.
+
+Making and sending patches
+==========================
+
+Once you have modified the source code of Nemiver, you can make a
+patch out of it and send it to nemiver-list gnome org, if you want to
+see the patch integrated to a subsequent version of the software.
+
+We strongly encourage you to learn to deal with patches.  Software
+engineering at proprietary places might ignore [at their own risk]
+what "Living the way of the patch" means, but us Free Software
+Hackers, live and die by patches.  We do live "The Way of the Patch".
+Everyday.  Patches represent the quantum of information that we share.
+By learning how to extract them, how to read them, how to split them,
+how to merge them, how to apply them and how to comment about them you
+actually learn how to hack in a decentralized manner.  This might look
+like a daunting task to begin with, but it is just an invaluable craft
+to develop.
+
+As a good starting point about the craft of patching, you can read the
+"Good patching practice" of the "Software Release Practice HOWTO" at
+http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/patching.html.
+
+We then encourage you to learn about the Git source control management
+system at http://git-scm.com.  It is true that you can hack against a
+Nemiver source tarball that you have downloaded from the Interweb, but
+we find it more convenient to use the canonical Git repository that
+the other Nemiver hackers use.  For that you need to learn Git.  The
+bonus point is that Git is so powerful, and fast, and tailored for
+hackers, that once you know enough about, you feel like a fish in the
+sea, dealing with patches.
+
+Okay, enough encouragement.  By now you should know enough to have
+made your first patch ;-)
+
+You should write a ChangeLog entry that describes what you did in the
+patch.  It's somewhat redundant with the patch itself.  That's fine.
+When communicating with other, there is a level of redundancy that we
+consider to be a virtue.  Our brains need that to make sure we
+understand the information we are dealing with.  And the GPL requires
+it.  The details of how the ChangeLog entry should look like are
+expressed in the file README.git-commit-messages.txt in the topmost
+directory of the source code.
+
+The ChangeLog entry is actually going to be put in the Git commit log
+of the patch.  During the source tarball release process, the
+maintainer issues the command "make changelog" that builds a ChangeLog
+file from the concatenated content of all the git commit logs.  That
+file is then distributed with the source tarball and gives a chance to
+people accessing the source tarball in an off-line context to have a
+chance to learn about what changed, roughly.
+
+When you send the patch to nemiver-list gnome org, you are kindly
+invited to send the commit log as well, in the format described in
+README.git-commit-messages.txt, so that the maintainer can commit that
+commit log as well as the patch itself.