diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 122 |
1 files changed, 97 insertions, 25 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea2bf80e7..17df42b87 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 view, 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 @@ -181,9 +244,16 @@ Or with stack: stack test --test-arguments='-p markdown' -It is often helpful to add `-j4` (run tests in parallel) -and `--hide-successes` (don't clutter output with successes) -to the test arguments as well. +It is often helpful to add `-j4` (run tests in parallel) and +`--hide-successes` (don't clutter output with successes) to the test +arguments as well. Collecting all options in a `cabal.project.local` +file in the project's root directory can help to keep `cabal` +commands short. E.g.: + + flags: +embed_data_files + tests: True + test-show-details: direct + test-options: -j4 --hide-successes If you add a new feature to pandoc, please add tests as well, following the pattern of the existing tests. The test suite code is in @@ -225,7 +295,11 @@ A good way to ensure no new warnings are introduced is to use a Git before creating a commit: #!/bin/sh - git diff --cached --name-only | grep '\.hs$' | xargs hlint + git diff --diff-filter=MA --cached --name-only | grep '\.hs$' | \ + xargs hlint --hint .hlint.yaml + +(If you are using GNU `xargs`, add the `-r` option immediately +after `xargs`.) Saving this to `.git/hooks/pre-commit`, and making the script executable, will prevent accidental introduction of potentially @@ -244,9 +318,6 @@ With stack: stack bench -You can also build `weigh-pandoc` (`stack build pandoc:weigh-pandoc`) -to get some statistics on memory usage. (Eventually this should -be incorporated into the benchmark suite.) Using the REPL -------------- @@ -258,10 +329,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 --------- @@ -305,7 +376,7 @@ The code -------- Pandoc has a publicly accessible git repository on -GitHub: <http://github.com/jgm/pandoc>. To get a local copy of the source: +GitHub: <https://github.com/jgm/pandoc>. To get a local copy of the source: git clone https://github.com/jgm/pandoc.git @@ -315,7 +386,7 @@ the pandoc library is in `src/`, the source for the tests is in The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and `Text.Pandoc.Generic` are in a separate library `pandoc-types`. The code can -be found in <http://github.com/jgm/pandoc-types>. +be found in <https://github.com/jgm/pandoc-types>. To build pandoc, you will need a working installation of the [Haskell platform]. @@ -335,11 +406,11 @@ The library is structured as follows: 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.Citeproc.*` contain the code for citation handling, + including an interface to the [citeproc] library. - `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]. + cabal flag is used. + - `Text.Pandoc.Emoji` is a thin wrapper around [emojis]. - `Text.Pandoc.Highlighting` contains the interface to the skylighting library, which is used for code syntax highlighting. - `Text.Pandoc.ImageSize` is a utility module containing functions for @@ -350,7 +421,6 @@ The library is structured as follows: - `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, @@ -378,14 +448,16 @@ you may want to consider submitting a pull request to the [closed issues]: https://github.com/jgm/pandoc/issues?q=is%3Aissue+is%3Aclosed [latest released version]: https://github.com/jgm/pandoc/releases/latest [Nightly builds]: https://github.com/jgm/pandoc/actions?query=workflow%3ANightly -[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss +[pandoc-discuss]: https://groups.google.com/group/pandoc-discuss [issue tracker]: https://github.com/jgm/pandoc/issues -[User's Guide]: http://pandoc.org/MANUAL.html -[FAQs]: http://pandoc.org/faqs.html -[EditorConfig]: http://editorconfig.org/ -[Haskell platform]: http://www.haskell.org/platform/ +[User's Guide]: https://pandoc.org/MANUAL.html +[FAQs]: https://pandoc.org/faqs.html +[EditorConfig]: https://editorconfig.org/ +[Haskell platform]: https://www.haskell.org/platform/ [hlint]: https://hackage.haskell.org/package/hlint -[hsb2hs]: http://hackage.haskell.org/package/hsb2hs +[citeproc]: https://hackage.haskell.org/package/citeproc +[emojis]: https://hackage.haskell.org/package/emojis +[hsb2hs]: https://hackage.haskell.org/package/hsb2hs [pre-commit hook]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks [GitHub labels]: https://github.com/jgm/pandoc/labels [good first issue]:https://github.com/jgm/pandoc/labels/good%20first%20issue |