Rename HACKING.txt to CONTRIBUTING.md and improve text

diff --git a/HACKING.txt b/CONTRIBUTING.md
similarity index 70%
rename from HACKING.txt
rename to CONTRIBUTING.md
index 50ed26f6c866e2b610805bf55cdb7db3fb70a44e..ed350e239bca62fa04789612470463b435a6af46 100644 (file)
--- a/HACKING.txt
+++ b/CONTRIBUTING.md
@@ -1,8 +1,64 @@
-Hacking ccache
-==============
+# Contributing to ccache
 
-Code formatting
----------------
+Want to contribute to ccache? Awesome!
+
+## Asking a question?
+
+It's OK to ask questions in the issue tracker for now.
+
+However, please consider posting your question to the
+[mailing list](https://lists.samba.org/mailman/listinfo/ccache/) instead, since
+you are more likely to get an answer there.
+
+## Reporting an issue?
+
+Please include at least the following information in your bug report:
+
+1. Which version of ccache you use.
+2. Which compiler you use, if applicable.
+3. Which operating system you use, if applicable.
+4. The problematic behavior you experienced (_actual behavior_).
+5. How you would like ccache to behave instead (_expected behavior_).
+6. Steps to reproduce the problematic behavior.
+
+## Contributing code?
+
+Great! You can create a pull request with your proposal on github, or you could
+post one or several patches to the
+[mailing list](https://lists.samba.org/mailman/listinfo/ccache/).
+
+### How to write commit messages
+
+* Write a summary (short description) on the first line.
+* Start the summary with a capital letter. Optional: prefix the short
+  description with a context followed by a colon.
+* The summary should be in imperative mood (see examples below).
+* The summary should not end with a period. It's a title and titles don't end
+  with a period.
+* If a longer description is wanted, add a second line empty and write the
+  longer description on line three and below.
+* Keep lines in the message at most 72 characters wide.
+
+Example 1:
+
+    Hash a delimiter string between parts to separate them
+
+    Previously, "gcc -I-O2 -c file.c" and "gcc -I -O2 -c file.c" would hash
+    to the same sum.
+
+Example 2:
+
+    win32: Add a space between filename and error string in x_fmmap()
+
+See also:
+
+* http://stopwritingramblingcommitmessages.com
+* http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+* https://github.com/erlang/otp/wiki/Writing-good-commit-messages
+
+### Code style
+
+#### Formatting
 
 * Use tabs for indenting and spaces for aligning C code.
 * Use 4 spaces for indenting other code (and spaces for aligning).
@@ -22,8 +78,7 @@ Code formatting
 Tip: Install the tool uncrustify <http://uncrustify.sourceforge.net> and then
 run "make uncrustify" to fix up source code formatting.
 
-Idioms
-------
+#### Idioms
 
 * Declare variables as late as convenient, not necessarily at the beginning of
   the scope.
@@ -37,38 +92,7 @@ Idioms
 * Use tmp_unlink() or x_unlink() instead of unlink().
 * Use x_rename() instead of rename().
 
-Other
------
+#### Other
 
 * Strive to minimize use of global variables.
 * Write test cases for new code.
-
-Commit messages
----------------
-
-* Write a summary (short description) on the first line.
-* Start the summary with a capital letter. Optional: prefix the short
-  description with a context followed by a colon.
-* The summary should be in imperative mood (see examples below).
-* The summary should not end with a period. It's a title and titles don't end
-  with a period.
-* If a longer description is wanted, add a second line empty and write the
-  longer description on line three and below.
-* Keep lines in the message at most 72 characters wide.
-
-Example 1:
-
-    Hash a delimiter string between parts to separate them
-
-    Previously, "gcc -I-O2 -c file.c" and "gcc -I -O2 -c file.c" would hash
-    to the same sum.
-
-Example 2:
-
-    win32: Add a space between filename and error string in x_fmmap()
-
-See also:
-
-* http://stopwritingramblingcommitmessages.com
-* http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-* https://github.com/erlang/otp/wiki/Writing-good-commit-messages