18 files changed, 776 insertions, 59 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index aa2182453d3..51cd67f47f1 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -23,6 +23,9 @@
 - [Namespaces](namespaces.md)
 - [Settings](settings.md)
 - [Keys](keys.md)
+- [Builds](builds.md)
+- [Build triggers](build_triggers.md)
+- [Build Variables](build_variables.md)
 
 ## Authentication
 
diff --git a/doc/api/build_triggers.md b/doc/api/build_triggers.md
new file mode 100644
index 00000000000..4a12e962b62
--- /dev/null
+++ b/doc/api/build_triggers.md
@@ -0,0 +1,108 @@
+# Build triggers
+
+You can read more about [triggering builds through the API](../ci/triggers/README.md).
+
+## List project triggers
+
+Get a list of project's build triggers.
+
+```
+GET /projects/:id/triggers
+```
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| `id`      | integer | yes      | The ID of a project |
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers"
+```
+
+```json
+[
+    {
+        "created_at": "2015-12-23T16:24:34.716Z",
+        "deleted_at": null,
+        "last_used": "2016-01-04T15:41:21.986Z",
+        "token": "fbdb730c2fbdb095a0862dbd8ab88b",
+        "updated_at": "2015-12-23T16:24:34.716Z"
+    },
+    {
+        "created_at": "2015-12-23T16:25:56.760Z",
+        "deleted_at": null,
+        "last_used": null,
+        "token": "7b9148c158980bbd9bcea92c17522d",
+        "updated_at": "2015-12-23T16:25:56.760Z"
+    }
+]
+```
+
+## Get trigger details
+
+Get details of project's build trigger.
+
+```
+GET /projects/:id/triggers/:token
+```
+
+| Attribute | Type    | required | Description              |
+|-----------|---------|----------|--------------------------|
+| `id`      | integer | yes      | The ID of a project      |
+| `token`   | string  | yes      | The `token` of a trigger |
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d"
+```
+
+```json
+{
+    "created_at": "2015-12-23T16:25:56.760Z",
+    "deleted_at": null,
+    "last_used": null,
+    "token": "7b9148c158980bbd9bcea92c17522d",
+    "updated_at": "2015-12-23T16:25:56.760Z"
+}
+```
+
+## Create a project trigger
+
+Create a build trigger for a project.
+
+```
+POST /projects/:id/triggers
+```
+
+| Attribute | Type    | required | Description              |
+|-----------|---------|----------|--------------------------|
+| `id`      | integer | yes      | The ID of a project      |
+
+```
+curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers"
+```
+
+```json
+{
+    "created_at": "2016-01-07T09:53:58.235Z",
+    "deleted_at": null,
+    "last_used": null,
+    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
+    "updated_at": "2016-01-07T09:53:58.235Z"
+}
+```
+
+## Remove a project trigger
+
+Remove a project's build trigger.
+
+```
+DELETE /projects/:id/triggers/:token
+```
+
+| Attribute | Type    | required | Description              |
+|-----------|---------|----------|--------------------------|
+| `id`      | integer | yes      | The ID of a project      |
+| `token`   | string  | yes      | The `token` of a project |
+
+```
+curl -X DELETE -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d"
+```
diff --git a/doc/api/build_variables.md b/doc/api/build_variables.md
new file mode 100644
index 00000000000..b96f1bdac8a
--- /dev/null
+++ b/doc/api/build_variables.md
@@ -0,0 +1,128 @@
+# Build Variables
+
+## List project variables
+
+Get list of a project's build variables.
+
+```
+GET /projects/:id/variables
+```
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| `id`      | integer | yes      | The ID of a project |
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables"
+```
+
+```json
+[
+    {
+        "key": "TEST_VARIABLE_1",
+        "value": "TEST_1"
+    },
+    {
+        "key": "TEST_VARIABLE_2",
+        "value": "TEST_2"
+    }
+]
+```
+
+## Show variable details
+
+Get the details of a project's specific build variable.
+
+```
+GET /projects/:id/variables/:key
+```
+
+| Attribute | Type    | required | Description           |
+|-----------|---------|----------|-----------------------|
+| `id`      | integer | yes      | The ID of a project   |
+| `key`     | string  | yes      | The `key` of a variable |
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/TEST_VARIABLE_1"
+```
+
+```json
+{
+    "key": "TEST_VARIABLE_1",
+    "value": "TEST_1"
+}
+```
+
+## Create variable
+
+Create a new build variable.
+
+```
+POST /projects/:id/variables
+```
+
+| Attribute | Type    | required | Description           |
+|-----------|---------|----------|-----------------------|
+| `id`      | integer | yes      | The ID of a project   |
+| `key`     | string  | yes      | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
+| `value`   | string  | yes      | The `value` of a variable |
+
+```
+curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables" -F "key=NEW_VARIABLE" -F "value=new value"
+```
+
+```json
+{
+    "key": "NEW_VARIABLE",
+    "value": "new value"
+}
+```
+
+## Update variable
+
+Update a project's build variable.
+
+```
+PUT /projects/:id/variables/:key
+```
+
+| Attribute | Type    | required | Description             |
+|-----------|---------|----------|-------------------------|
+| `id`      | integer | yes      | The ID of a project     |
+| `key`     | string  | yes      | The `key` of a variable   |
+| `value`   | string  | yes      | The `value` of a variable |
+
+```
+curl -X PUT -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/NEW_VARIABLE" -F "value=updated value"
+```
+
+```json
+{
+    "key": "NEW_VARIABLE",
+    "value": "updated value"
+}
+```
+
+## Remove variable
+
+Remove a project's build variable.
+
+```
+DELETE /projects/:id/variables/:key
+```
+
+| Attribute | Type    | required | Description             |
+|-----------|---------|----------|-------------------------|
+| `id`      | integer | yes      | The ID of a project     |
+| `key`     | string  | yes      | The `key` of a variable |
+
+```
+curl -X DELETE -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/VARIABLE_1"
+```
+
+```json
+{
+    "key": "VARIABLE_1",
+    "value": "VALUE_1"
+}
+```
diff --git a/doc/api/builds.md b/doc/api/builds.md
new file mode 100644
index 00000000000..ecb50754c88
--- /dev/null
+++ b/doc/api/builds.md
@@ -0,0 +1,360 @@
+# Builds API
+
+## List project builds
+
+Get a list of builds in a project.
+
+```
+GET /projects/:id/builds
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| scope     | string|array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
+
+### Example of request
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds"
+```
+
+### Example of response
+
+```json
+[
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2015-12-24T15:51:21.802Z",
+        "download_url": null,
+        "finished_at": "2015-12-24T17:54:27.895Z",
+        "id": 7,
+        "name": "teaspoon",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": "2015-12-24T17:54:27.722Z",
+        "status": "failed",
+        "tag": false,
+        "user": {
+            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+            "bio": null,
+            "created_at": "2015-12-21T13:14:24.077Z",
+            "id": 1,
+            "is_admin": true,
+            "linkedin": "",
+            "name": "Administrator",
+            "skype": "",
+            "state": "active",
+            "twitter": "",
+            "username": "root",
+            "web_url": "http://gitlab.dev/u/root",
+            "website_url": ""
+        }
+    },
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2015-12-24T15:51:21.727Z",
+        "download_url": null,
+        "finished_at": "2015-12-24T17:54:24.921Z",
+        "id": 6,
+        "name": "spinach:other",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": "2015-12-24T17:54:24.729Z",
+        "status": "failed",
+        "tag": false,
+        "user": {
+            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+            "bio": null,
+            "created_at": "2015-12-21T13:14:24.077Z",
+            "id": 1,
+            "is_admin": true,
+            "linkedin": "",
+            "name": "Administrator",
+            "skype": "",
+            "state": "active",
+            "twitter": "",
+            "username": "root",
+            "web_url": "http://gitlab.dev/u/root",
+            "website_url": ""
+        }
+    }
+]
+```
+
+## List commit builds
+
+Get a list of builds for specific commit in a project.
+
+```
+GET /projects/:id/repository/commits/:sha/builds
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| sha       | string  | yes      | The SHA id of a commit |
+| scope     | string|array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
+
+### Example of request
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds"
+```
+
+### Example of response
+
+```json
+[
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2016-01-11T10:13:33.506Z",
+        "download_url": null,
+        "finished_at": "2016-01-11T10:14:09.526Z",
+        "id": 69,
+        "name": "rubocop",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": null,
+        "status": "canceled",
+        "tag": false,
+        "user": null
+    },
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2015-12-24T15:51:21.957Z",
+        "download_url": null,
+        "finished_at": "2015-12-24T17:54:33.913Z",
+        "id": 9,
+        "name": "brakeman",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": "2015-12-24T17:54:33.727Z",
+        "status": "failed",
+        "tag": false,
+        "user": {
+            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+            "bio": null,
+            "created_at": "2015-12-21T13:14:24.077Z",
+            "id": 1,
+            "is_admin": true,
+            "linkedin": "",
+            "name": "Administrator",
+            "skype": "",
+            "state": "active",
+            "twitter": "",
+            "username": "root",
+            "web_url": "http://gitlab.dev/u/root",
+            "website_url": ""
+        }
+    }
+]
+```
+
+## Get a single build
+
+Get a single build of a project
+
+```
+GET /projects/:id/builds/:build_id
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| build\_id  | integer | yes      | The ID of a build   |
+
+### Example of request
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8"
+```
+
+### Example of response
+
+```json
+{
+    "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2015-12-24T16:51:14.000+01:00",
+        "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+        "message": "Test the CI integration.",
+        "short_id": "0ff3ae19",
+        "title": "Test the CI integration."
+    },
+    "coverage": null,
+    "created_at": "2015-12-24T15:51:21.880Z",
+    "download_url": null,
+    "finished_at": "2015-12-24T17:54:31.198Z",
+    "id": 8,
+    "name": "rubocop",
+    "ref": "master",
+    "runner": null,
+    "stage": "test",
+    "started_at": "2015-12-24T17:54:30.733Z",
+    "status": "failed",
+    "tag": false,
+    "user": {
+        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+        "bio": null,
+        "created_at": "2015-12-21T13:14:24.077Z",
+        "id": 1,
+        "is_admin": true,
+        "linkedin": "",
+        "name": "Administrator",
+        "skype": "",
+        "state": "active",
+        "twitter": "",
+        "username": "root",
+        "web_url": "http://gitlab.dev/u/root",
+        "website_url": ""
+    }
+}
+```
+
+## Cancel a build
+
+Cancel a single build of a project
+
+```
+POST /projects/:id/builds/:build_id/cancel
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| build\_id | integer | yes      | The ID of a build   |
+
+### Example of request
+
+```
+curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel"
+```
+
+### Example of response
+
+```json
+{
+    "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2015-12-24T16:51:14.000+01:00",
+        "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+        "message": "Test the CI integration.",
+        "short_id": "0ff3ae19",
+        "title": "Test the CI integration."
+    },
+    "coverage": null,
+    "created_at": "2016-01-11T10:13:33.506Z",
+    "download_url": null,
+    "finished_at": "2016-01-11T10:14:09.526Z",
+    "id": 69,
+    "name": "rubocop",
+    "ref": "master",
+    "runner": null,
+    "stage": "test",
+    "started_at": null,
+    "status": "canceled",
+    "tag": false,
+    "user": null
+}
+```
+
+## Retry a build
+
+Retry a single build of a project
+
+```
+POST /projects/:id/builds/:build_id/retry
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| build\_id | integer | yes      | The ID of a build   |
+
+### Example of request
+
+```
+curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry"
+```
+
+### Example of response
+
+```json
+{
+    "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2015-12-24T16:51:14.000+01:00",
+        "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+        "message": "Test the CI integration.",
+        "short_id": "0ff3ae19",
+        "title": "Test the CI integration."
+    },
+    "coverage": null,
+    "created_at": "2016-01-11T10:13:33.506Z",
+    "download_url": null,
+    "finished_at": null,
+    "id": 69,
+    "name": "rubocop",
+    "ref": "master",
+    "runner": null,
+    "stage": "test",
+    "started_at": null,
+    "status": "pending",
+    "tag": false,
+    "user": null
+}
+```
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 37d74216c1b..241229221db 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -76,7 +76,10 @@ Parameters:
       "updated_at": "2013-09-30T13: 46: 02Z"
     },
     "archived": false,
-    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png"
+    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
+    "shared_runners_enabled": true,
+    "forks_count": 0,
+    "star_count": 0
   },
   {
     "id": 6,
@@ -129,7 +132,11 @@ Parameters:
       }
     },
     "archived": false,
-    "avatar_url": null
+    "avatar_url": null,
+    "shared_runners_enabled": true,
+    "forks_count": 0,
+    "star_count": 0,
+    "runners_token": "b8547b1dc37721d05889db52fa2f02"
   }
 ]
 ```
@@ -244,7 +251,11 @@ Parameters:
     }
   },
   "archived": false,
-  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png"
+  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
+  "shared_runners_enabled": true,
+  "forks_count": 0,
+  "star_count": 0,
+  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b"
 }
 ```
 
diff --git a/doc/api/users.md b/doc/api/users.md
index 773fe36d277..b7fc903825e 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -558,7 +558,8 @@ Parameters:
 
 - `uid` (required) - id of specified user
 
-Will return `200 OK` on success, or `404 User Not Found` is user cannot be found.
+Will return `200 OK` on success, `404 User Not Found` is user cannot be found or 
+`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
 
 ## Unblock user
 
@@ -572,4 +573,5 @@ Parameters:
 
 - `uid` (required) - id of specified user
 
-Will return `200 OK` on success, or `404 User Not Found` is user cannot be found.
+Will return `200 OK` on success, `404 User Not Found` is user cannot be found or
+`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md
index 3b5008ccdb4..018ca22dbbd 100644
--- a/doc/ci/api/builds.md
+++ b/doc/ci/api/builds.md
@@ -18,18 +18,62 @@ Returns:
 
 ```json
 {
-  "id" : 79,
-  "commands" : "",
-  "path" : "",
-  "ref" : "",
-  "sha" : "",
-  "project_id" : 6,
-  "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-  "before_sha" : ""
+  "id": 48584,
+  "ref": "0.1.1",
+  "tag": true,
+  "sha": "d63117656af6ff57d99e50cc270f854691f335ad",
+  "status": "success",
+  "name": "pages",
+  "token": "9dd60b4f1a439d1765357446c1084c",
+  "stage": "test",
+  "project_id": 479,
+  "project_name": "test",
+  "commands": "echo commands",
+  "repo_url": "http://gitlab-ci-token:token@gitlab.example/group/test.git",
+  "before_sha": "0000000000000000000000000000000000000000",
+  "allow_git_fetch": false,
+  "options": {
+    "image": "docker:image",
+    "artifacts": {
+      "paths": [
+        "public"
+      ]
+    },
+    "cache": {
+      "paths": [
+        "vendor"
+      ]
+    }
+  },
+  "timeout": 3600,
+  "variables": [
+    {
+      "key": "CI_BUILD_TAG",
+      "value": "0.1.1",
+      "public": true
+    }
+  ],
+  "depends_on_builds": [
+    {
+      "id": 48584,
+      "ref": "0.1.1",
+      "tag": true,
+      "sha": "d63117656af6ff57d99e50cc270f854691f335ad",
+      "status": "success",
+      "name": "build",
+      "token": "9dd60b4f1a439d1765357446c1084c",
+      "stage": "build",
+      "project_id": 479,
+      "project_name": "test",
+      "artifacts_file": {
+        "filename": "artifacts.zip",
+        "size": 0
+      }
+    }
+  ]
 }
 ```
 
-
 ### Update details of an existing build
 
     PUT /ci/builds/:id
diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md
index df2507a34d0..0bd32b78201 100644
--- a/doc/development/doc_styleguide.md
+++ b/doc/development/doc_styleguide.md
@@ -5,18 +5,21 @@ it organized and easy to find.
 
 ## Naming
 
-- Use underscores for all names, including new documentation and images
+- When creating a new document and it has more than one word in its name,
+  make sure to use underscores instead of spaces or dashes (`-`). For example,
+  a proper naming would be `import_projects_from_github.md`. The same rule
+  applies to images.
 
 ## Text
 
 - Split up long lines, this makes it much easier to review and edit. Only
-  double line breaks are shown as a full line break in GitLab markdown.
+  double line breaks are shown as a full line break in [GitLab markdown][gfm].
   80-100 characters is a good line length
 - Make sure that the documentation is added in the correct directory and that
   there's a link to it somewhere useful
 - Do not duplicate information
 - Be brief and clear
-- Whenever it applies, add documents in alphabetical order
+- Unless there's a logical reason not to, add documents in alphabetical order
 - Write in US English
 - Use [single spaces][] instead of double spaces
 
@@ -34,27 +37,27 @@ it organized and easy to find.
 
 - Add only one H1 title in each document, by adding `#` at the beginning of
   it (when using markdown). For subheadings, use `##`, `###` and so on
-- For subtitles, make sure to start with the largest and go down, meaning:
-  `#` for the title, `##` for subtitles and `###` for subtitles of the subtitles, etc.
-- Avoid putting numbers in Markdown headings. Numbers shift hence documentation
-  anchor links shift too which eventually leads to dead links.
-- When introducing a new doc, be careful for the headings to be grammatically
-  and syntactically correct. It is advised to mention one or all of the
-  following GitLab members for a review: `@axil`, `@rspeicher`, `@dblessing`,
-  `@ashleys`, `@nearlythere`. This is to ensure that no document with
-  wrong heading is going live without an audit, thus preventing dead links and
-  redirection issues when corrected.
+- Avoid putting numbers in headings. Numbers shift, hence documentation anchor
+  links shift too, which eventually leads to dead links. If you think it is
+  compelling to add numbers in headings, make sure to at least discuss it with
+  someone in the Merge Request
+- When introducing a new document, be careful for the headings to be
+  grammatically and syntactically correct. It is advised to mention one or all
+  of the following GitLab members for a review: `@axil`, `@rspeicher`,
+  `@dblessing`, `@ashleys`, `@nearlythere`. This is to ensure that no document
+  with wrong heading is going live without an audit, thus preventing dead links
+  and redirection issues when corrected
 - Leave exactly one newline after a heading
 
 ## Links
 
-- If the link sets the paragraph spanning across multiple lines, do not use
+- If a link makes the paragraph to span across multiple lines, do not use
   the regular Markdown approach: `[Text](https://example.com)`. Instead use
   `[Text][identifier]` and at the very bottom of the document add:
-  `[identifier]: https://example.com`. This is another way to make Markdown
-  links which keeps the document clear and concise. Extra points if you also
+  `[identifier]: https://example.com`. This is another way to create Markdown
+  links which keeps the document clear and concise. Bonus points if you also
   add an alternative text: `[identifier]: https://example.com "Alternative text"`
-  that appears when hovering your mouse on a link.
+  that appears when hovering your mouse on a link
 
 ## Images
 
@@ -71,7 +74,7 @@ Inside the document:
 
 - The Markdown way of using an image inside a document is:
   `![Proper description what the image is about](img/document_image_title.png)`
-- Always use a proper description what the image is about. That way, when a
+- Always use a proper description for what the image is about. That way, when a
   browser fails to show the image, this text will be used as an alternative
   description
 - If there are consecutive images with little text between them, always add
@@ -90,16 +93,19 @@ Inside the document:
 
 - Every piece of documentation that comes with a new feature should declare the
   GitLab version that feature got introduced. Right below the heading add a
-  note: `_**Note:** This feature was introduced in GitLab CE 8.3_`
+  note: `_**Note:** This feature was introduced in GitLab 8.3_`
 - If possible every feature should have a link to the MR that introduced it.
-  The above note would be transformed to:
-  `_**Note:** This feature was [introduced][ce-1242] in GitLab CE 8.3_`, where
-  the link is named after the repository (CE) and the MR number, and the
-  [link identifier](#links) is used.
+  The above note would be then transformed to:
+  `_**Note:** This feature was [introduced][ce-1242] in GitLab 8.3_`, where
+  the [link identifier](#links) is named after the repository (CE) and the MR
+  number
+- If the feature is only in GitLab EE, don't forget to mention it, like:
+  `_**Note:** This feature was introduced in GitLab EE 8.3_`. Otherwise, leave
+  this mention out
 
 ## API
 
-Here is a list of must have items. Use them in this exact order that appears
+Here is a list of must-have items. Use them in the exact order that appears
 on this document. Further explanation is given below.
 
 - Every method must have the REST API request. For example:
@@ -201,7 +207,7 @@ titled ssh-key to user's account which has an id of 25.
 
 Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
 to escape them when possible. In the example below we create a new issue which
-contains spaces in its title. Watch how spaces are escaped using the `%20`
+contains spaces in its title. Observe how spaces are escaped using the `%20`
 ASCII code.
 
 ```bash
@@ -222,3 +228,4 @@ curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -d "restricted_signup_domai
 
 [cURL]: http://curl.haxx.se/ "cURL website"
 [single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
+[gfm]: http://doc.gitlab.com/ce/markdown/markdown.html#newlines "GitLab flavored markdown documentation"
diff --git a/doc/incoming_email/README.md b/doc/incoming_email/README.md
index 86d205ba7a5..4cfb8402943 100644
--- a/doc/incoming_email/README.md
+++ b/doc/incoming_email/README.md
@@ -74,10 +74,11 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow [these
 
     As mentioned, the part after `+` in the address is ignored, and any email sent here will end up in the mailbox for `incoming@gitlab.example.com`/`gitlab-incoming@gmail.com`.
 
-1. Reconfigure GitLab for the changes to take effect:
+1. Reconfigure GitLab and restart mailroom for the changes to take effect:
 
     ```sh
     sudo gitlab-ctl reconfigure
+    sudo gitlab-ctl restart mailroom
     ```
 
 1. Verify that everything is configured correctly:
diff --git a/doc/incoming_email/postfix.md b/doc/incoming_email/postfix.md
index 18bf3db1744..787d21f7f8f 100644
--- a/doc/incoming_email/postfix.md
+++ b/doc/incoming_email/postfix.md
@@ -84,7 +84,12 @@ The instructions make the assumption that you will be using the email address `i
     quit
     ```
 
-    (Note: The `.` is a literal period on its own line)
+    _**Note:** The `.` is a literal period on its own line._
+
+    _**Note:** If you receive an error after entering `rcpt to: incoming@localhost`
+    then your Postfix `my_network` configuration is not correct. The error will
+    say 'Temporary lookup failure'. See
+    [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._
 
 1. Check if the `incoming` user received the email:
     
@@ -131,7 +136,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
 1. Test the new setup:
     
     1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_.
-    2. Check if the `incoming` user received the email:
+    1. Check if the `incoming` user received the email:
     
         ```sh
         su - incoming
@@ -152,6 +157,12 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
         q
         ```
 
+    _**Note:** If `mail` returns an error `Maildir: Is a directory` then your
+    version of `mail` doesn't support Maildir style mailboxes. Install
+    `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then,
+    try the above steps again, substituting `heirloom-mailx` for the `mail`
+    command._
+
 1. Log out of the `incoming` account and go back to being `root`:
 
     ```sh
diff --git a/doc/install/installation.md b/doc/install/installation.md
index e645445df2a..00030729a4b 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -135,11 +135,11 @@ gitlab-workhorse we need a Go compiler. The instructions below assume you
 use 64-bit Linux. You can find downloads for other platforms at the [Go download
 page](https://golang.org/dl).
 
-    curl -O --progress https://storage.googleapis.com/golang/go1.5.1.linux-amd64.tar.gz
-    echo '46eecd290d8803887dec718c691cc243f2175fe0  go1.5.1.linux-amd64.tar.gz' | shasum -c - && \
-      sudo tar -C /usr/local -xzf go1.5.1.linux-amd64.tar.gz
+    curl -O --progress https://storage.googleapis.com/golang/go1.5.3.linux-amd64.tar.gz
+    echo '43afe0c5017e502630b1aea4d44b8a7f059bf60d7f29dfd58db454d4e4e0ae53  go1.5.3.linux-amd64.tar.gz' | shasum -c - && \
+      sudo tar -C /usr/local -xzf go1.5.3.linux-amd64.tar.gz
     sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/
-    rm go1.5.1.linux-amd64.tar.gz
+    rm go1.5.3.linux-amd64.tar.gz
 
 ## 4. System Users
 
diff --git a/doc/integration/saml.md b/doc/integration/saml.md
index 1632e42f701..8841dbdb7c6 100644
--- a/doc/integration/saml.md
+++ b/doc/integration/saml.md
@@ -78,6 +78,18 @@ On the sign in page there should now be a SAML button below the regular sign in
 
 ## Troubleshooting
 
-If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, this likely indicates that GitLab could not get the email address for the SAML user.
+If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page,
+this likely indicates that GitLab could not get the email address for the SAML user.
 
-Make sure the IdP provides a claim containing the user's email address, using claim name 'email' or 'mail'. The email will be used to automatically generate the GitLab username.
\ No newline at end of file
+Make sure the IdP provides a claim containing the user's email address, using claim name
+'email' or 'mail'. The email will be used to automatically generate the GitLab username.
+
+If after signing in into your SAML server you are redirected back to the sign in page and
+no error is displayed, check your `production.log` file. It will most likely contain the
+message `Can't verify CSRF token authenticity`. This means that there is an error during
+the SAML request, but this error never reaches GitLab due to the CSRF check.
+
+To bypass this you can add `skip_before_action :verify_authenticity_token` to the
+`omniauth_callbacks_controller.rb` file. This will allow the error to hit GitLab,
+where it can then be seen in the usual logs, or as a flash message in the login
+screen.
\ No newline at end of file
diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md
index 49f98ded046..612376e3a49 100644
--- a/doc/system_hooks/system_hooks.md
+++ b/doc/system_hooks/system_hooks.md
@@ -96,6 +96,7 @@ X-Gitlab-Event: System Hook
  "project_path_with_namespace": "jsmith/storecloud",
                   "user_email": "johnsmith@gmail.com",
                    "user_name": "John Smith",
+               "user_username": "johnsmith",
                      "user_id": 41,
           "project_visibility": "private",
 }
@@ -115,6 +116,7 @@ X-Gitlab-Event: System Hook
  "project_path_with_namespace": "jsmith/storecloud",
                   "user_email": "johnsmith@gmail.com",
                    "user_name": "John Smith",
+               "user_username": "johnsmith",
                      "user_id": 41,
           "project_visibility": "private",
 }
@@ -129,6 +131,7 @@ X-Gitlab-Event: System Hook
         "email": "js@gitlabhq.com",
    "event_name": "user_create",
          "name": "John Smith",
+     "username": "js",
       "user_id": 41
 }
 ```
@@ -142,6 +145,7 @@ X-Gitlab-Event: System Hook
         "email": "js@gitlabhq.com",
    "event_name": "user_destroy",
          "name": "John Smith",
+     "username": "js",
       "user_id": 41
 }
 ```
@@ -215,6 +219,7 @@ X-Gitlab-Event: System Hook
     "group_path": "storecloud",
     "user_email": "johnsmith@gmail.com",
      "user_name": "John Smith",
+ "user_username": "johnsmith",
        "user_id": 41
 }
 ```
@@ -231,6 +236,7 @@ X-Gitlab-Event: System Hook
     "group_path": "storecloud",
     "user_email": "johnsmith@gmail.com",
      "user_name": "John Smith",
+ "user_username": "johnsmith",
        "user_id": 41
 }
 ```
diff --git a/doc/workflow/importing/github_importer/importer.png b/doc/workflow/importing/github_importer/importer.png
deleted file mode 100644
index 57636717571..00000000000
--- a/doc/workflow/importing/github_importer/importer.png
+++ /dev/null
diff --git a/doc/workflow/importing/github_importer/new_project_page.png b/doc/workflow/importing/github_importer/new_project_page.png
deleted file mode 100644
index 002f22d81d7..00000000000
--- a/doc/workflow/importing/github_importer/new_project_page.png
+++ /dev/null
diff --git a/doc/workflow/importing/img/import_projects_from_github_importer.png b/doc/workflow/importing/img/import_projects_from_github_importer.png
new file mode 100644
index 00000000000..f744dc06f81
--- /dev/null
+++ b/doc/workflow/importing/img/import_projects_from_github_importer.png
diff --git a/doc/workflow/importing/img/import_projects_from_github_new_project_page.png b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png
new file mode 100644
index 00000000000..86be35acb37
--- /dev/null
+++ b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png
diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md
index 2027a055c37..f693f430a42 100644
--- a/doc/workflow/importing/import_projects_from_github.md
+++ b/doc/workflow/importing/import_projects_from_github.md
@@ -1,20 +1,44 @@
 # Import your project from GitHub to GitLab

 

-It takes just a couple of steps to import your existing GitHub projects to GitLab. Keep in mind that it is possible only if

-GitHub support is enabled on your GitLab instance. You can read more about GitHub support [here](http://doc.gitlab.com/ce/integration/github.html)

+_**Note:** In order to enable the GitHub import setting, you should first

+enable the [GitHub integration][gh-import] in your GitLab instance._

 

-If you want to import from a GitHub Enterprise instance, you need to use GitLab Enterprise; please see the [EE docs for the GitHub integration](http://doc.gitlab.com/ee/integration/github.html).

+At its current state, GitHub importer can import:

 

-* Sign in to GitLab.com and go to your dashboard.

-* To get to the importer page, you need to go to the "New project" page.

+- the repository description (introduced in GitLab 7.7)

+- the git repository data (introduced in GitLab 7.7)

+- the issues (introduced in GitLab 7.7)

+- the pull requests (introduced in GitLab 8.4)

+- the wiki pages (introduced in GitLab 8.4)

 

-![New project page](github_importer/new_project_page.png)

+It is not yet possible to import your labels, milestones and cross-repository

+pull requests (those from forks). We are working on improving this in the near

+future.

 

-* Click on the "Import project from GitHub" link and you will be redirected to GitHub for permission to access your projects. After accepting, you'll be automatically redirected to the importer.

+The importer page is visible when you [create a new project][new-project].

+Click on the **GitHub** link and you will be redirected to GitHub for

+permission to access your projects. After accepting, you'll be automatically

+redirected to the importer.

 

-![Importer page](github_importer/importer.png)

+![New project page on GitLab](img/import_projects_from_github_new_project_page.png)

 

-* To import a project, you can simple click "Add". The importer will import your repository, issues, and pull requests. Once the importer is done, a new GitLab project will be created with your imported data.

+---

 

-### Note

-When you import your projects from GitHub, it is not possible to keep your labels, milestones, and cross-repository pull requests. We are working on improving this in the near future.

+While at the GitHub importer page, you can see the import statuses of your

+GitHub projects. Those that are being imported will show a _started_ status,

+those already imported will be green, whereas those that are not yet imported

+have an **Import** button on the right side of the table. If you want, you can

+import all your GitHub projects in one go by hitting **Import all projects**

+in the upper left corner.

+

+![GitHub importer page](img/import_projects_from_github_importer.png)

+

+---

+

+The importer will create any new namespaces if they don't exist or in the

+case the namespace is taken, the project will be imported on the user's

+namespace.

+

+[gh-import]: ../../integration/github.md "GitHub integration"

+[ee-gh]: http://doc.gitlab.com/ee/integration/github.html "GitHub integration for GitLab EE"

+[new-project]: ../../gitlab-basics/create-project.md "How to create a new project in GitLab"