@@ -0,0 +1,90 @@
1+Contributing to pandoc
2+======================
3+
4+Found a bug?
5+------------
6+
7+Bug reports are welcome! Please report all bugs on pandoc's github
8+[issue tracker].
9+
10+Before you submit a bug report, search the (open *and* closed) issues to make
11+sure the issue hasn't come up before. Also, check the [User's Guide] and [FAQs]
12+for anything relevant.
13+
14+Make sure you can reproduce the bug with the latest released version of pandoc
15+(or, even better, the development version).
16+
17+Your report should give detailed instructions for how to reproduce the problem,
18+including
19+
20+ * the exact command line used
21+ * the exact input used
22+ * the output received
23+ * the output you expected instead
24+
25+A small test case (just a few lines) is ideal. If your input is large,
26+spend some time trying to whittle it down to the minimum necessary to
27+illustrate the problem.
28+
29+Have an idea for a new feature?
30+-------------------------------
31+
32+Lay out the rationale for the feature you're requesting. Why would this
33+feature be useful? Consider also any possible drawbacks, including breaking
34+old documents.
35+
36+It is best to discuss a potential new feature on [pandoc-discuss]
37+before opening an issue.
38+
39+Patches and pull requests
40+-------------------------
41+
42+Patches and pull requests are welcome. Please follow these guidelines:
43+
44+1. Each patch should make a single logical change (fix a bug, add
45+ a feature, clean up some code, add documentation). Everything
46+ related to that change should be included (including tests and
47+ documentation), and nothing unrelated should be included.
48+
49+2. Follow the stylistic conventions you find in the existing
50+ panadoc code. Use spaces, not tabs, and wrap code to 80 columns.
51+ Always include type signatures for top-level functions.
52+
53+3. Your code should compile without warnings (`-Wall` clean).
54+
55+4. Run the tests to make sure your code does not introduce new bugs.
56+ (See below under [Tests](#tests).)
57+
58+5. It is a good idea to add test cases for the bug you are fixing. (See below
59+ under [Tests](#tests).) If you are adding a new writer or reader,
60+ you must include tests.
61+
62+6. If you are adding a new feature, include updates to the README.
63+
64+7. Before you put time into a nontrivial patch, it is a good idea to
65+ discuss it on [pandoc-discuss], especially if it is for a new feature
66+ (rather than fixing a bug).
67+
68+8. All code must be released under the general license governing pandoc
69+ (GPL v2).
70+
71+9. It is better not to introduce new dependencies. Dependencies on
72+ external C libraries should especially be avoided.
73+
74+Tests
75+-----
76+
77+Tests can be run as follows:
78+
79+ cabal configure --enable-tests
80+ cabal build
81+ cabal test
82+
83+The test program is `tests/test-pandoc.hs`.
84+
85+
86+[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
87+[issue tracker]: https://github.com/jgm/pandoc/issues
88+[User's Guide]: http://johnmacfarlane.net/pandoc/README.html
89+[FAQs]: http://johnmacfarlane.net/pandoc/faqs.html
90+