aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlbert Krewinkel <albert@zeitkraut.de>2020-11-27 18:13:02 +0100
committerGitHub <noreply@github.com>2020-11-27 09:13:02 -0800
commit3a2d993165e44103e6cde8a977542e6adedf913d (patch)
treebbe17cf2ecd0ab97c731bf423f4efcfa270a83e4
parent97b70d20bbd266d627a402360b0fd682f53355a3 (diff)
downloadpandoc-3a2d993165e44103e6cde8a977542e6adedf913d.tar.gz
CONTRIBUTING: add section "How can I help?" (#6892)
Also adds a paragraph aimed at highlighting the importance of feature maintenance.
-rw-r--r--CONTRIBUTING.md73
1 files changed, 68 insertions, 5 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ea2bf80e7..b2dc8313d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,64 @@
Contributing to pandoc
======================
+Welcome to pandoc! Very soon after its beginnings in 2006, pandoc
+has been influenced, improved, and modified, by users, devs, and
+newcomers alike. The project thrives on its active community. It is
+great to have you here.
+
+How can I help?
+---------------
+
+There are many ways in which you can support pandoc. Here are a few
+ideas:
+
+ * Participate in online discussions. The [pandoc-discuss] mailing
+ list is a good place for this. This gives valuable input and
+ makes it easier to improve the program.
+
+ * Help with questions. Every request that is answered by the wider
+ community frees time for programming contributors. This will
+ speed up development of new features and issue fixes. Don't
+ underestimate your knowledge, please share it!
+
+ Good places to help are the [pandoc-discuss] mailing list, Q/A
+ sites like StackOverflow, community forums (e.g.
+ [RStudio][RStudio Community], [Zettlr][Zettlr Forum]), and, for
+ technical questions, the GitHub [issue tracker].
+
+ * Write or improve documentation. If you ran into a problem which
+ took more time to figure out than expected, please consider to
+ save other users from the same experience. People writing the
+ documentation tend to lack an outside few, so please help
+ provide one. Good documentation is both difficult and extremely
+ important.
+
+ The official docs are not the only place for documentation.
+ Pandoc also has a [Wiki][pandoc wiki]. Private blogs can serve
+ as documentation just as the official manual can.
+
+ * Contribute code. No matter whether it's a small fix in a format
+ template or a huge lump of Haskell code: help is welcome. It's
+ usually a good idea to talk about the plans early, as this can
+ prevent unnecessary work. See below for more information.
+
+ * Last but not least: consider funding the development and
+ maintenance of pandoc financially. You can find sponsor buttons
+ on the [pandoc website] and the [GitHub repository][GitHub
+ repo].
+
+A rich ecosystem of libraries, editors, filters, and templates has
+developed around pandoc; conversely, pandoc builds and depends on a
+large number of libraries. Contributing to any of these projects is
+another way that can help to ensure stability, and to keep pushing
+the boundaries of what is possible with pandoc.
+
+[RStudio Community]: https://community.rstudio.com/
+[Zettlr Forum]: https://forum.zettlr.com/
+[pandoc wiki]: https://github.com/jgm/pandoc/wiki
+[pandoc website]: https://pandoc.org
+[GitHub repo]: https://github.com/jgm/pandoc
+
Have a question?
----------------
@@ -105,7 +163,12 @@ 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]
+Features are very rarely "implement and forget", as all code must be
+maintained. This is especially relevant for large or complex
+contributions. It is helpful to be sympathetic to that fact, and to
+communicate future plans and availability clearly.
+
+Any potential new feature is best discussed on [pandoc-discuss]
before opening an issue.
Patches and pull requests
@@ -258,10 +321,10 @@ a ghci REPL for working with pandoc. With [stack], use
We recommend using the following `.ghci` file (which can be
placed in the source directory):
- :set -fobject-code
- :set -XTypeSynonymInstances
- :set -XScopedTypeVariables
- :set -XOverloadedStrings
+ :set -fobject-code
+ :set -XTypeSynonymInstances
+ :set -XScopedTypeVariables
+ :set -XOverloadedStrings
Profiling
---------