From 4b151fb68452d0531d5f0d6c3b48aaeb2fb02d10 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sun, 14 Apr 2013 22:11:19 -0700 Subject: [PATCH] Improved CONTRIBUTING.md. --- CONTRIBUTING.md | 128 ++++++++++++++++++++++++++++++++++++++++-------- 1 file 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). -1. Each patch should make a single logical change (fix a bug, add +Please follow these guidelines: + +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: . 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 . + +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