Merge master into issue_12758issue_12758

3 files changed, 52 insertions, 27 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index e3fc5a09f21..71bb01e0d51 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -44,13 +44,11 @@ The following documentation is for the [internal CI API](ci/README.md):
 
 ## Authentication
 
-All API requests require authentication. You need to pass a `private_token`
-parameter via query string or header. If passed as a header, the header name
-must be `PRIVATE-TOKEN` (uppercase and with a dash instead of an underscore).
-You can find or reset your private token in your account page (`/profile/account`).
+All API requests require authentication via a token. There are three types of tokens 
+available: private tokens, OAuth 2 tokens, and personal access tokens.
 
-If `private_token` is invalid or omitted, then an error message will be
-returned with status code `401`:
+If a token is invalid or omitted, an error message will be returned with 
+status code `401`:
 
 ```json
 {
@@ -58,42 +56,56 @@ returned with status code `401`:
 }
 ```
 
-API requests should be prefixed with `api` and the API version. The API version
-is defined in [`lib/api.rb`][lib-api-url].
+### Private Tokens
 
-Example of a valid API request:
+You need to pass a `private_token` parameter via query string or header. If passed as a 
+header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of 
+an underscore). You can find or reset your private token in your account page
+(`/profile/account`).
 
-```shell
-GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK
-```
+### OAuth 2 Tokens
 
-Example of a valid API request using cURL and authentication via header:
+You can use an OAuth 2 token to authenticate with the API by passing it either in the
+`access_token` parameter or in the `Authorization` header.
+
+Example of using the OAuth2 token in the header:
 
 ```shell
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"
+curl -H "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v3/projects
 ```
 
-The API uses JSON to serialize data. You don't need to specify `.json` at the
-end of an API URL.
+Read more about [GitLab as an OAuth2 client](oauth2.md).
+
+### Personal Access Tokens
 
-## Authentication with OAuth2 token
+> **Note:** This feature was [introduced][ce-3749] in GitLab 8.8
 
-Instead of the `private_token` you can transmit the OAuth2 access token as a
-header or as a parameter.
+You can create as many personal access tokens as you like from your GitLab 
+profile (`/profile/personal_access_tokens`); perhaps one for each application
+that needs access to the GitLab API.
 
-Example of OAuth2 token as a parameter:
+Once you have your token, pass it to the API using either the `private_token`
+parameter or the `PRIVATE-TOKEN` header.
+
+## Basic Usage
+
+API requests should be prefixed with `api` and the API version. The API version
+is defined in [`lib/api.rb`][lib-api-url].
+
+Example of a valid API request:
 
 ```shell
-curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN
+GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK
 ```
 
-Example of OAuth2 token as a header:
+Example of a valid API request using cURL and authentication via header:
 
 ```shell
-curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"
 ```
 
-Read more about [GitLab as an OAuth2 client](oauth2.md).
+The API uses JSON to serialize data. You don't need to specify `.json` at the
+end of an API URL.
 
 ## Status codes
 
@@ -330,3 +342,4 @@ programming languages. Visit the [GitLab website] for a complete list.
 
 [GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API"
 [lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb
+[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 02e024ca15a..8a7547e5322 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -34,6 +34,15 @@ First, you need to provide information on whether the migration can be applied:
 3. online with errors on new instances while migrating
 4. offline (needs to happen without app servers to prevent db corruption)
 
+For example: 
+
+```
+# rubocop:disable all
+# Migration type: online without errors (works on previous version and new one)
+class MyMigration < ActiveRecord::Migration
+...
+```
+
 It is always preferable to have a migration run online. If you expect the migration
 to take particularly long (for instance, if it loops through all notes),
 this is valuable information to add.
@@ -48,7 +57,6 @@ be possible to downgrade in case of a vulnerability or bugs.
 In your migration, add a comment describing how the reversibility of the
 migration was tested.
 
-
 ## Removing indices
 
 If you need to remove index, please add a condition like in following example:
@@ -70,6 +78,7 @@ so:
 
 ```
 class MyMigration < ActiveRecord::Migration
+  include Gitlab::Database::MigrationHelpers
   disable_ddl_transaction!
 
   def change
@@ -90,8 +99,11 @@ value of `10` you'd write the following:
 
 ```
 class MyMigration < ActiveRecord::Migration
+  include Gitlab::Database::MigrationHelpers
+  disable_ddl_transaction!
+  
   def up
-    add_column_with_default(:projects, :foo, :integer, 10)
+    add_column_with_default(:projects, :foo, :integer, default: 10)
   end
 
   def down
diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md
index 98f44a5b07b..fe4485e148a 100644
--- a/doc/workflow/notifications.md
+++ b/doc/workflow/notifications.md
@@ -20,7 +20,7 @@ Each of these settings have levels of notification:
 * Participating - receive notifications from related resources
 * Watch - receive notifications from projects or groups user is a member of
 * Global - notifications as set at the global settings
-* Custom - Notification is set based on events selected by the user.(Available only in project level)
+* Custom - user will receive notifications when mentioned, is participant and custom selected events.
 
 #### Global Settings