Improved CONTRIBUTING.md.

1 files changed, 108 insertions, 20 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a3c9ac874..8225449a2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -23,15 +23,17 @@ including
   * the output you expected instead
 
 A small test case (just a few lines) is ideal.  If your input is large,
-spend some time trying to whittle it down to the minimum necessary to
-illustrate the problem.
+try to whittle it down to the minimum necessary to illustrate the problem.
 
 Have an idea for a new feature?
 -------------------------------
 
-Lay out the rationale for the feature you're requesting.  Why would this
-feature be useful?  Consider also any possible drawbacks, including breaking
-old documents.
+First, search [pandoc-discuss] and the issue tracker (both open and closed
+issues) to make sure that the idea has not been discussed before.
+
+Explain the rationale for the feature you're requesting.  Why would this
+feature be useful?  Consider also any possible drawbacks, including backwards
+compatibility, new library dependencies, and performance issues.
 
 It is best to discuss a potential new feature on [pandoc-discuss]
 before opening an issue.
@@ -39,31 +41,36 @@ before opening an issue.
 Patches and pull requests
 -------------------------
 
-Patches and pull requests are welcome.  Please follow these guidelines:
+Patches and pull requests are welcome.  Before you put time into a nontrivial
+patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
+for a new feature (rather than fixing a bug).
+
+Please follow these guidelines:
 
-1.  Each patch should make a single logical change (fix a bug, add
+1.  Each patch (commit) should make a single logical change (fix a bug, add
     a feature, clean up some code, add documentation).  Everything
     related to that change should be included (including tests and
     documentation), and nothing unrelated should be included.
 
-2.  Follow the stylistic conventions you find in the existing
-    panadoc code.  Use spaces, not tabs, and wrap code to 80 columns.
+2.  The first line of the commit message should be a short description
+    of the whole commit (ideally <= 50 characters).  Then there should
+    be a blank line, followed by a more detailed description of the
+    change.
+
+3.  Follow the stylistic conventions you find in the existing
+    pandoc code.  Use spaces, not tabs, and wrap code to 80 columns.
     Always include type signatures for top-level functions.
 
-3.  Your code should compile without warnings (`-Wall` clean).
+4.  Your code should compile without warnings (`-Wall` clean).
 
-4.  Run the tests to make sure your code does not introduce new bugs.
-    (See below under [Tests](#tests).)
+5.  Run the tests to make sure your code does not introduce new bugs.
+    (See below under [Tests](#tests).)  All tests should pass.
 
-5.  It is a good idea to add test cases for the bug you are fixing.  (See below
-    under [Tests](#tests).)  If you are adding a new writer or reader,
+6.  It is a good idea to add test cases for the bug you are fixing.  (See
+    below under [Tests](#tests).)  If you are adding a new writer or reader,
     you must include tests.
 
-6.  If you are adding a new feature, include updates to the README.
-
-7.  Before you put time into a nontrivial patch, it is a good idea to
-    discuss it on [pandoc-discuss], especially if it is for a new feature
-    (rather than fixing a bug).
+7.  If you are adding a new feature, include updates to the README.
 
 8.  All code must be released under the general license governing pandoc
     (GPL v2).
@@ -82,9 +89,90 @@ Tests can be run as follows:
 
 The test program is `tests/test-pandoc.hs`.
 
+Benchmarks can be enabled by passing the `--enable-benchmarks` flag
+to `cabal configure`, and run using `cabal bench`.
+
+The code
+--------
+
+Pandoc has a publicly accessible git repository on
+github: <http://github.com/jgm/pandoc>.  To get a local copy of the source:
+
+    git clone git://github.com/jgm/pandoc.git
+
+Note:  after cloning the repository (and in the future after pulling from it),
+you should do
+
+    git submodule update --init
+
+to pull in changes to the templates (`data/templates/`).  You can automate this
+by creating a file `.git/hooks/post-merge` with the contents:
+
+    #!/bin/sh
+    git submodule update --init
+
+and making it executable:
+
+    chmod +x .git/hooks/post-merge
+
+The source for the main pandoc program is `pandoc.hs`.  The source for
+the pandoc library is in `src/`, the source for the tests is in
+`tests/`, and the source for the benchmarks is in `benchmark/`.
+
+The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
+`Text.Pandoc.Generics` are in a separate library `pandoc-types`.  The code can
+be found in a <http://github.com/jgm/pandoc-types>.
+
+To build pandoc, you will need a working installation of the
+[Haskell platform].
+
+The library is structured as follows:
+
+  - `Text.Pandoc` is a top-level module that exports what is needed
+    by most users of the library.  Any patches that add new readers
+    or writers will need to make changes here, too.
+  - `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
+    used for representing a pandoc document.
+  - `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
+    building pandoc documents programatically.
+  - `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
+    you to promote functions that operate on parts of pandoc documents
+    to functions that operate on whole pandoc documents, walking the
+    tree automatically.
+  - `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
+    are the writers.
+  - `Text.Pandoc.Biblio` is a utility module for formatting citations
+    using citeproc-hs.
+  - `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
+    cabal flag is used.  It is generated from `src/Text/Pandoc/Data.hsb` using
+    the preprocessor [hsb2hs].
+  - `Text.Pandoc.Highlighting` contains the interface to the
+    highlighting-kate library, which is used for code syntax highlighting.
+  - `Text.Pandoc.ImageSize` is a utility module containing functions for
+    calculating image sizes from the contents of image files.
+  - `Text.Pandoc.MIME` contains functions for associating MIME types
+    with extensions.
+  - `Text.Pandoc.Options` defines reader and writer options.
+  - `Text.Pandoc.PDF` contains functions for producing a PDF from a
+    LaTeX source.
+  - `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
+  - `Text.Pandoc.Pretty` is a pretty-printing library specialized to
+    the needs of pandoc.
+  - `Text.Pandoc.SelfContained` contains functions for making an HTML
+    file "self-contained," by importing remotely linked images, CSS,
+    and javascript and turning them into `data:` URLs.
+  - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
+  - `Text.Pandoc.Slides` contains functions for splitting a markdown document
+    into slides, using the conventions described in the README.
+  - `Text.Pandoc.Templates` defines pandoc's templating system.
+  - `Text.Pandoc.UTF8` contains functions for converting text to and from
+    UTF8 bytestrings (strict and lazy).
+  - `Text.Pandoc.UUID` contains functions for generating UUIDs.
+  - `Text.Pandoc.XML` contains functions for formatting XML.
 
 [pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
 [issue tracker]: https://github.com/jgm/pandoc/issues
 [User's Guide]: http://johnmacfarlane.net/pandoc/README.html
 [FAQs]:  http://johnmacfarlane.net/pandoc/faqs.html
-
+[Haskell platform]: http://www.haskell.org/platform/
+[hsb2hs]: http://hackage.haskell.org/package/hsb2hs