diff --git a/docs/release-source/release.md b/docs/release-source/release.md
index 902f8eb68..b183d5ed4 100644
--- a/docs/release-source/release.md
+++ b/docs/release-source/release.md
@@ -15,6 +15,7 @@ This page contains the entire Sinon.JS API documentation along with brief introd
 - [Stubs](./stubs)
 - [Mocks](./mocks)
 - [Spy calls](./spy-call)
+- [Promises](./promises)
 - [Fake timers](./fake-timers)
 - [Fake <code>XHR</code> and server](./fake-xhr-and-server)
 - [JSON-P](./json-p)
diff --git a/docs/release-source/release/promises.md b/docs/release-source/release/promises.md
new file mode 100644
index 000000000..cbc836c80
--- /dev/null
+++ b/docs/release-source/release/promises.md
@@ -0,0 +1,52 @@
+---
+layout: page
+title: Promises - Sinon.JS
+breadcrumb: promises
+---
+
+### Introduction
+
+`promise` allows to create fake promises that expose their internal state and can be resolved or rejected on demand.
+
+### Creating a promise
+
+```js
+var promise = sinon.promise();
+```
+
+#### Creating a promise with a fake executor
+
+```js
+var executor = sinon.fake();
+var promise = sinon.promise(executor);
+```
+
+#### Creating a promise with custom executor
+
+```js
+var promise = sinon.promise(function (resolve, reject) {
+  // ...
+});
+```
+
+### Promise API
+
+#### `promise.status`
+
+The internal status of the promise. One of `pending`, `resolved`, `rejected`.
+
+#### `promise.resolvedValue`
+
+The promise resolved value.
+
+#### `promise.rejectedValue`
+
+The promise rejected value.
+
+#### `promise.resolve(value)`
+
+Resolves the promise with the given value. Throws if the promise is not `pending`.
+
+#### `promise.reject(value)`
+
+Rejects the promise with the given value. Throws if the promise is not `pending`.