diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..67d291ed
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and is a rolling release.
+
+## 2019-10-02
+
+### Added
+
+- The `run` derivation now uses [gitignore](https://github.com/hercules-ci/gitignore#readme)
+
+- Custom hooks can now be added
+
+### Changed
+
+- Hooks configuration is now module-based (using the module system, like NixOS).
+  `.pre-commit-config.yaml` is now obsolete with `nix-pre-commit-hooks`. Translate it to the `hooks` argument. For example:
+
+  ```
+  pre-commit-check = nix-pre-commit-hooks.run {
+    src = ./.;
+    hooks = {
+      elm-format.enable = true;
+      ormolu.enable = true;
+      shellcheck.enable = true;
+    };
+  };
+  ```
+
+### Fixed
+
+- Some small improvements to the installation script (`shellHook`)
diff --git a/README.md b/README.md
index f3d4a122..321ecb82 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,9 @@ eval "$shellHook"
 
 Everyone is encouraged to add new hooks.
 
+<!-- TODO generate option docs -->
+Have a look at the [existing hooks](modules/hooks.nix) and the [options](modules/pre-commit.nix).
+
 There's no guarantee the hook will be accepted, but the general guidelines are:
 
 - Nix closure of the tool should be small e.g. `< 50MB`