@@ -1,6 +1,64 @@
1Contributing to pandoc
1Contributing to pandoc
2======================
2======================
4+Welcome to pandoc! Very soon after its beginnings in 2006, pandoc
5+has been influenced, improved, and modified, by users, devs, and
6+newcomers alike. The project thrives on its active community. It is
7+great to have you here.
12+There are many ways in which you can support pandoc. Here are a few
15+ * Participate in online discussions. The [pandoc-discuss] mailing
16+ list is a good place for this. This gives valuable input and
17+ makes it easier to improve the program.
19+ * Help with questions. Every request that is answered by the wider
20+ community frees time for programming contributors. This will
21+ speed up development of new features and issue fixes. Don't
22+ underestimate your knowledge, please share it!
24+ Good places to help are the [pandoc-discuss] mailing list, Q/A
25+ sites like StackOverflow, community forums (e.g.
26+ [RStudio][RStudio Community], [Zettlr][Zettlr Forum]), and, for
27+ technical questions, the GitHub [issue tracker].
29+ * Write or improve documentation. If you ran into a problem which
30+ took more time to figure out than expected, please consider to
31+ save other users from the same experience. People writing the
32+ documentation tend to lack an outside few, so please help
33+ provide one. Good documentation is both difficult and extremely
36+ The official docs are not the only place for documentation.
37+ Pandoc also has a [Wiki][pandoc wiki]. Private blogs can serve
38+ as documentation just as the official manual can.
40+ * Contribute code. No matter whether it's a small fix in a format
41+ template or a huge lump of Haskell code: help is welcome. It's
42+ usually a good idea to talk about the plans early, as this can
43+ prevent unnecessary work. See below for more information.
45+ * Last but not least: consider funding the development and
46+ maintenance of pandoc financially. You can find sponsor buttons
47+ on the [pandoc website] and the [GitHub repository][GitHub
50+A rich ecosystem of libraries, editors, filters, and templates has
51+developed around pandoc; conversely, pandoc builds and depends on a
52+large number of libraries. Contributing to any of these projects is
53+another way that can help to ensure stability, and to keep pushing
54+the boundaries of what is possible with pandoc.
56+[RStudio Community]: https://community.rstudio.com/
57+[Zettlr Forum]: https://forum.zettlr.com/
58+[pandoc wiki]: https://github.com/jgm/pandoc/wiki
59+[pandoc website]: https://pandoc.org
60+[GitHub repo]: https://github.com/jgm/pandoc
4Have a question?
62Have a question?
5----------------
63----------------
@@ -105,7 +163,12 @@ Explain the rationale for the feature you're requesting. Why would this
105feature be useful? Consider also any possible drawbacks, including backwards
163feature be useful? Consider also any possible drawbacks, including backwards
106compatibility, new library dependencies, and performance issues.
164compatibility, new library dependencies, and performance issues.
166+Features are very rarely "implement and forget", as all code must be
167+maintained. This is especially relevant for large or complex
168+contributions. It is helpful to be sympathetic to that fact, and to
169+communicate future plans and availability clearly.
108−It is best to discuss a potential new feature on [pandoc-discuss]
171+Any potential new feature is best discussed on [pandoc-discuss]
109before opening an issue.
172before opening an issue.
111Patches and pull requests
174Patches and pull requests
@@ -258,10 +321,10 @@ a ghci REPL for working with pandoc. With [stack], use
258We recommend using the following `.ghci` file (which can be
321We recommend using the following `.ghci` file (which can be
259placed in the source directory):
322placed in the source directory):
261− :set -fobject-code
324+ :set -fobject-code
262− :set -XTypeSynonymInstances
325+ :set -XTypeSynonymInstances
263− :set -XScopedTypeVariables
326+ :set -XScopedTypeVariables
264− :set -XOverloadedStrings
327+ :set -XOverloadedStrings