Skip to content

Latest commit

 

History

History
96 lines (68 loc) · 3.2 KB

CONTRIBUTING.md

File metadata and controls

96 lines (68 loc) · 3.2 KB

Contributing to lua-filters

Happy to have you here! Below you can find guidance on the best way to contribute to this collection of Lua filters.

Bugs reports and feature requests

All contributions are welcome!

Please report all bugs on the GitHub issue tracker.

Please note that all filters usually target the latest pandoc version, although we may lag behind sometimes. It is considered a bug if a filter produces wrong results for the latest pandoc version; older pandoc versions are not necessarily supported, although we usually strive to do so.

A bug report is most useful if it gives detailed, reproducible instructions. Additionally, it should include

  • the pandoc version,
  • the exact command line used,
  • the exact input used,
  • the output received, and
  • the output you expected instead.

This will allow us to help you more quickly.

Pull requests

Whether a small patch or a full new filters, we love getting pull requests. Consistency is important, especially for a project with multiple parts written by many contributors. That's why PRs should follow the filter structure outlined below.

Filter Structure

The filters come with these components:

  • README.md describing the filter; if the filter depends on additional programs, the document should list those requirements and describe how they can be installed.

    Please keep in mind that a key design goal of Markdown was readability. The README should be pleasant to read even as plain text. This includes keeping lines below 80 chars or, better yet, below 66 chars.

  • The main Lua filter script; besides the code, it should also contain a small header with author, copyright, and licensing information. All filters must be licensed under the MIT license.

    Lua code should follow the Olivine Labs Lua style guide. The tl;dr is: use snake_case for most names and keep lines below 80 chars.

  • Makefile to run the tests. The only hard requirement is the existence of a .PHONY target named test which can be used to test correctness.

  • sample.md or a similar file demonstrating how the filter can be used. The sample file doubles as test input.

  • A file containing the expected output when using the filter on the sample input. Multiple such files can be provided if different filter configurations are to be tested.

All components should be bundled in a single directory.

Configuration

Filters are expected to be readily usable by a wide range of users. It should not be necessary to edit any source files, so it often makes sense to keep a filter configurable.

There are two main methods to configure a filter: environment variables and special metadata values. The diagram-generator filter supports both and can serve as a good reference.

Commits

Please follow the usual guidelines for git commits: keep commits atomic, self-contained, and add a brief but clear commit message. This guide by Chris Beams is a good resource if you'd like to learn more.