git.iko.soy/typeable/aeson
on wip/yuras/scanner help sign in
typeable/aeson/CONTRIBUTING.md
98 lines 3.0 kB history raw
1# Documenting changes
3Changes that affect users of aeson should be mentioned in `changelog.md`. It should contain
4* A description
5* The level of change, see [PVP](https://wiki.haskell.org/Package_versioning_policy)
6* Where applicable
7 * How to migrate existing code
8 * When it should be used
9 * What it supersedes
11Add this entry under an `## Upcoming` header above existing releases.
13The exact format of entries is not important as we'll go through everything before a release is made.
15# Style guide
17* 4 space indentation
19## Pragmas
21* One pragma on each line
22* No alignment
23* Sort lexicographically
25```haskell
26{-# LANGUAGE BangPatterns #-}
27{-# LANGUAGE CPP #-}
28{-# LANGUAGE DataKinds #-}
29```
31## Module declaration and exports
33* Opening paren on its own line
34* Prefix with commas
35* End with `) where`
37```haskell
38module Data.Aeson.Types.ToJSON
39 (
40 -- * Core JSON classes
41 ToJSON(..)
42 -- * Liftings to unary and binary type constructors
43 , ToJSON1(..)
44 , toJSON1
45 ) where
46```
48## Imports
50* No alignment of import lists or qualifications
51* Sort lexicographically (qualified imports will be last)
52* No space between types and constructor lists
53* Sort identifiers in import lists lexicographically
55```haskell
56import BarBar as B ((<>), foo)
57import Foo as F
58import Qux (Q(..), q)
59import qualified A
60```
62## Development Workflow (If you plan on using Stack)
64Here we outline a general workflow new contributors could adopt for a nice incremental development experience.
66The root folder consists of two stack-*.yaml config files.
681. stack-nightly.yaml - Config file defines all the settings to build and test any changes.
692. stack-bench.yaml - Used to run benchmark tests.
703. stack-ffi-unescape.yaml - This is for replacing certain parts with a C-implementation.
72Therefore, a ghci development experience would be:
741. `stack ghci --stack-yaml stack-nightly.yaml --test`
752. :r to recompile
763. `main` to run all tests, or `:main --pattern Foo` to run specific tests matched by pattern.
78Some discussion on this topic can also be found here [here](https://github.com/bos/aeson/issues/733)
80Of course before submitting a PR, the following steps are recommended:
821. 'stack test --stack-yaml stack-nightly.yaml` - Run the entire suite of tests
832. `make hlint` - Run hlint on the source folders.
843. 'stack test --stack-yaml stack-bench.yaml` - Run the benchmark tests if you believe your changes could affect the benchmarks.
86## Development Workflow (If you plan on using Cabal)
88A ghci development experience would be:
901. `cabal new-repl test:tests`
912. `:r` to recompile
923. `Main.main` to run all tests, or `:m Main; :main --pattern Foo` to run specific tests matched by pattern.
94Of course before submitting a PR, the following steps are recommended:
961. `cabal new-test` - Run the entire suite of tests
972. `make hlint` - Run hlint on the source folders.
983. Uncomment the `benchmarks` line in `cabal.project` - Run the benchmark tests if you believe your changes could affect the benchmarks.