@@ -0,0 +1,70 @@
1+# Contributing
2+
3+Issues (bugs, feature requests or otherwise feedback) may be reported in
4+[the GitHub issue tracker for this
5+project](https://github.com/tweag/ormolu/issues). Pull requests are also
6+welcome.
7+
8+When contributing to this repository, please first discuss the change you
9+wish to make via an issue, unless it's entirely trivial (typo fixes, etc.).
10+If there is already an issue that describes the change you have in mind,
11+comment on it indicating that you're going to work on that. This way we can
12+avoid the situation when several people work on the same thing.
13+
14+Please make sure that all non-trivial changes are described in commit
15+messages and PR descriptions.
16+
17+## What to hack on?
18+
19+Right now there are two options for people who want to contribute:
20+
21+* [Implementing rendering of AST][cover-ast]. This is the main focus right
22+ now because we want to have a MVP which can render all syntactical
23+ constructions found in Haskell source code. Once that is achieved we'll
24+ polish the tool iteratively.
25+* [Fixing bugs][bugs]. If this seems more interesting than implementing
26+ rendering of AST, you are welcome to do this as well.
27+
28+## Implementing rendering of AST
29+
30+The `Ormolu.Printer.Combinators` module provides a DSL for rendering of GHC
31+AST. You'll probably only need this one module for writing new rendering
32+functions. The module documents how to use the printing combinators it
33+provides. Consult the Haddocks to learn more about them.
34+
35+Create new modules corresponding to the things you want to render under
36+`Ormolu.Printer.Meat`. For example, there are `Ormolu.Printer.Meat.Type` and
37+`Ormolu.Printer.Meat.Declaration.Data`.
38+
39+Concrete rendering functions get their names by appending `p_` to the name
40+of the type which describes a particular part of AST. For example, the
41+function for rendering types is correspondingly:
42+
43+```haskell
44+p_hsType :: HsType GhcPs -> R ()
45+```
46+
47+In general rendering functions like this take 1 or more arguments and
48+produce `R ()` which is a rendering action.
49+
50+### Testing
51+
52+Testing has been taken good care of and now it amounts to just adding
53+examples under `data/examples`. Each example is a pair of files:
54+`<example-name>.hs` for input and `<example-name>-out.hs` for corresponding
55+expected output.
56+
57+Testing is performed as following:
58+
59+* Given snippet of source code is parsed and pretty-printed.
60+* The result of printing is parsed back again and the AST is compared to the
61+ AST obtained from the original file. They should match.
62+* The output of printer is checked against the expected output.
63+* Idempotency property is verified: formatting already formatted code
64+ results in exactly the same output.
65+
66+Examples can be organized in sub-directories, see the existing ones for
67+inspiration.
68+
69+[cover-ast]: https://github.com/tweag/ormolu/issues?q=is%3Aissue+is%3Aopen+label%3Acovering-ghc-ast
70+[bugs]: https://github.com/tweag/ormolu/issues?q=is%3Aissue+is%3Aopen+label%3Abug