@@ -35,7 +35,34 @@ Some things we like:
3535Though we aren't sticklers for style, the `.stylish-haskell.yaml` and `HLint.hs`
3636files in the repository provide a good baseline for consistency.
3737
38−**Important**: please do not modify the changelog files nor the versions of the servant packages you are sending patches for. We take care of this before every release and do it uniformly for all the servant packages, so there's no need to worry about this for your pull requests.
38+**Important**: please do not modify the versions of the servant packages you are sending patches for.
39+
40+## Changelog entries
41+
42+We experiment with using [changelog-d tool](https://github.com/phadej/changelog-d) to assemble changelogs.
43+You are not required to install it.
44+
45+In each PR please add a file to `changelog.d` directory named after issue you are solving or the pull request itself (in a separate commit after you know the pull request number). For example
46+
47+```cabal
48+synopsis: One sentence summary of the change.
49+prs: #1219
50+issues: #1028
51+
52+description: {
53+
54+A longer description. Small changes don't need this.
55+Bigger ones definitely do, for example we try to include migration hints
56+for breaking changes.
57+
58+However if you don't know what to write, that's ok too.
59+
60+By the way, the braces around are omitted when the file is parsed.
61+They can be used so the field doesn't need to be indented, which is handy
62+for prose.
63+
64+}
65+```
3966
4067## PR process
4168