Merge branch 'master' of gitlab.com:gitlab-org/gitlab-ce into docs-add-badges

8 files changed, 147 insertions, 19 deletions

diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index 1962392a9eb..d5a4acff481 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -44,6 +44,7 @@ the `author` field. GitLab team members **should not**.
 - _Any_ contribution from a community member, no matter how small, **may** have
   a changelog entry regardless of these guidelines if the contributor wants one.
   Example: "Fixed a typo on the search results page. (Jane Smith)"
+- Performance improvements **should** have a changelog entry.
 
 ## Writing good changelog entries
 
diff --git a/doc/development/emails.md b/doc/development/emails.md
index 4dbf064fd75..73cac82caf0 100644
--- a/doc/development/emails.md
+++ b/doc/development/emails.md
@@ -74,6 +74,24 @@ See the [Rails guides] for more info.
 
 1. Reply by email should now be working.
 
+## Email namespace
+
+If you need to implement a new feature which requires a new email handler, follow these rules:
+
+ - You must choose a namespace. The namespace cannot contain `/` or `+`, and cannot match `\h{16}`.
+ - If your feature is related to a project, you will append the namespace **after** the project path, separated by a `+`
+ - If you have different actions in the namespace, you add the actions **after** the namespace separated by a `+`. The action name cannot contain `/` or `+`, , and cannot match `\h{16}`.
+ - You will register your handlers in `lib/gitlab/email/handler.rb`
+
+Therefore, these are the only valid formats for an email handler:
+
+ - `path/to/project+namespace`
+ - `path/to/project+namespace+action`
+ - `namespace`
+ - `namespace+action`
+
+Please note that `path/to/project` is used in GitLab Premium as handler for the Service Desk feature.
+
 ---
 
 [Return to Development documentation](README.md)
diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index c1170fa3b13..944b56a65f1 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -523,7 +523,7 @@ export default new Vuex.Store({
 ```
 _Note:_ If the state of the application is too complex, an individual file for the state may be better.
 
-#### `actions.js`
+##### `actions.js`
 An action commits a mutatation. In this file, we will write the actions that will call the respective mutation:
 
 ```javascript
@@ -550,7 +550,7 @@ import { mapActions } from 'vuex';
 };
 ```
 
-#### `getters.js`
+##### `getters.js`
 Sometimes we may need to get derived state based on store state, like filtering for a specific prop. This can be done through the `getters`:
 
 ```javascript
@@ -573,7 +573,7 @@ import { mapGetters } from 'vuex';
 };
 ```
 
-#### `mutations.js`
+##### `mutations.js`
 The only way to actually change state in a Vuex store is by committing a mutation.
 
 ```javascript
@@ -586,7 +586,7 @@ The only way to actually change state in a Vuex store is by committing a mutatio
   };
 ```
 
-#### `mutations_types.js`
+##### `mutations_types.js`
 From [vuex mutations docs][vuex-mutations]:
 > It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application.
 
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 26abf967dcf..4f9ca1920a5 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -7,6 +7,67 @@ be replaced by Gitaly API calls.
 Visit the [Gitaly Migration Board](https://gitlab.com/gitlab-org/gitaly/boards/331341) for current
 status of the migration.
 
+## Developing new Git features
+
+Starting with Gitlab 10.8, all new Git features should be developed in
+Gitaly.
+
+> This is a new process that is not clearly defined yet. If you want
+to contribute a Git feature and you're getting stuck, reach out to the
+Gitaly team or `@jacobvosmaer-gitlab`.
+
+By 'new feature' we mean any method or class in `lib/gitlab/git` that is
+called from outside `lib/gitlab/git`. For new methods that are called
+from inside `lib/gitlab/git`, see 'Modifying existing Git features'
+below.
+
+There should be no new code that touches Git repositories via
+disk access (e.g. Rugged, `git`, `rm -rf`) anywhere outside
+`lib/gitlab/git`.
+
+The process for adding new Gitaly features is:
+
+- exploration / prototyping
+- design and create a new Gitaly RPC [in gitaly-proto](https://gitlab.com/gitlab-org/gitaly-proto)
+- release a new version of gitaly-proto
+- write implementation and tests for the RPC [in Gitaly](https://gitlab.com/gitlab-org/gitaly), in Go or Ruby
+- release a new version of Gitaly
+- write client code in gitlab-ce/ee, gitlab-workhorse or gitlab-shell that calls the new Gitaly RPC
+
+These steps often overlap. It is possible to use an unreleased version
+of Gitaly and gitaly-proto during testing and development.
+
+- See the [Gitaly repo](https://gitlab.com/gitlab-org/gitaly/blob/master/CONTRIBUTING.md#development-and-testing-with-a-custom-gitaly-proto) for instructions on writing server side code with an unreleased protocol.
+- See [below](#running-tests-with-a-locally-modified-version-of-gitaly) for instructions on running gitlab-ce tests with a modified version of Gitaly.
+- In GDK run `gdk install` and restart `gdk run` (or `gdk run app`) to use a locally modified Gitaly version for development
+
+### Gitaly-ruby
+
+It is possible to implement and test RPC's in Gitaly using Ruby code,
+in
+[gitaly-ruby](https://gitlab.com/gitlab-org/gitaly/tree/master/ruby).
+This should make it easier to contribute for developers who are less
+comfortable writing Go code.
+
+There is documentation for this approach in [the Gitaly
+repo](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md).
+
+## Modifying existing Git features
+
+If you modify existing Git features in `lib/gitlab/git` you need to make
+sure the changes also work in Gitaly. Because we are still in the
+migration process there are a number of subtle pitfalls. Features that
+have been migrated have dual implementations (Gitaly and local). The
+Gitaly implementation may or may not use a vendored (and therefore
+possibly outdated) copy of the local implementation in `lib/gitlab/git`.
+
+To avoid unexpected problems and conflicts, all changes to
+`lib/gitlab/git` need to be approved by a member of the Gitaly team.
+
+For the time being, while the Gitaly migration is still in progress,
+there should be no Enterprise Edition-only Git code in
+`lib/gitlab/git`. Also no mixins.
+
 ## Feature Flags
 
 Gitaly makes heavy use of [feature flags](feature_flags.md).
@@ -99,10 +160,14 @@ end
 
 ## Running tests with a locally modified version of Gitaly
 
-Normally, gitlab-ce/ee tests use a local clone of Gitaly in `tmp/tests/gitaly`
-pinned at the version specified in GITALY_SERVER_VERSION. If you want
-to run tests locally against a modified version of Gitaly you can
-replace `tmp/tests/gitaly` with a symlink.
+Normally, gitlab-ce/ee tests use a local clone of Gitaly in
+`tmp/tests/gitaly` pinned at the version specified in
+`GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports
+`=my-branch` syntax to use a custom branch in gitlab-org/gitaly. If
+you want to run tests locally against a modified version of Gitaly you
+can replace `tmp/tests/gitaly` with a symlink. This is much faster
+because the `=my-branch` syntax forces a Gitaly re-install each time
+you run `rspec`.
 
 ```shell
 rm -rf tmp/tests/gitaly
diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index 856ef882453..b1bec84a2f3 100644
--- a/doc/development/i18n/externalization.md
+++ b/doc/development/i18n/externalization.md
@@ -131,6 +131,9 @@ There is also and alternative method to [translate messages from validation erro
 
 ### Interpolation
 
+Placeholders in translated text should match the code style of the respective source file.
+For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript.
+
 - In Ruby/HAML:
 
     ```ruby
@@ -141,11 +144,19 @@ There is also and alternative method to [translate messages from validation erro
 
     ```js
     import { __, sprintf } from '~/locale';
-    sprintf(__('Hello %{username}'), { username: 'Joe' }) => 'Hello Joe'
+
+    sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe'
     ```
 
-The placeholders should match the code style of the respective source file.
-For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript.
+    By default, `sprintf` escapes the placeholder values.
+    If you want to take care of that yourself, you can pass `false` as third argument.
+
+    ```js
+    import { __, sprintf } from '~/locale';
+
+    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }); // => 'This is &lt;strong&gt;bold&lt;/strong&gt;'
+    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }, false); // => 'This is <strong>bold</strong>'
+    ```
 
 ### Plurals
 
diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md
index cf62314bc29..5185d843ccb 100644
--- a/doc/development/i18n/proofreader.md
+++ b/doc/development/i18n/proofreader.md
@@ -23,6 +23,7 @@ are very appreciative of the work done by translators and proofreaders!
 - Italian
   - Paolo Falomo - [GitLab](https://gitlab.com/paolofalomo), [Crowdin](https://crowdin.com/profile/paolo.falomo)
 - Japanese
+  - Yamana Tokiuji - [GitLab](https://gitlab.com/tokiuji), [Crowdin](https://crowdin.com/profile/yamana)
 - Korean
   - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang)
   - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve)
diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md
index 637099d1e83..899efb398cd 100644
--- a/doc/development/new_fe_guide/development/components.md
+++ b/doc/development/new_fe_guide/development/components.md
@@ -1,3 +1,21 @@
 # Components
 
-> TODO: Add content
+## Graphs
+
+We have a lot of graphing libraries in our codebase to render graphs. In an effort to improve maintainability, new graphs should use [D3.js](https://d3js.org/). If a new graph is fairly simple, consider implementing it in SVGs or HTML5 canvas.
+
+We chose D3 as our library going forward because of the following features:
+
+* [Tree shaking webpack capabilities.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40)
+* [Compatible with vue.js as well as vanilla javascript.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40)
+
+D3 is very popular across many projects outside of GitLab:
+
+* [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html)
+* [plot.ly](https://plot.ly/)
+* [Droptask](https://www.droptask.com/)
+
+Within GitLab, D3 has been used for the following notable features
+
+* [Prometheus graphs](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html)
+* Contribution calendars
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md
index 0c63f51cb45..0a6f402d5d2 100644
--- a/doc/development/testing_guide/frontend_testing.md
+++ b/doc/development/testing_guide/frontend_testing.md
@@ -152,19 +152,33 @@ is sufficient (and saves you some time).
 ### Live testing and focused testing
 
 While developing locally, it may be helpful to keep karma running so that you
-can get instant feedback on as you write tests and modify code.  To do this
-you can start karma with `npm run karma-start`.  It will compile the javascript
+can get instant feedback on as you write tests and modify code. To do this
+you can start karma with `yarn run karma-start`. It will compile the javascript
 assets and run a server at `http://localhost:9876/` where it will automatically
-run the tests on any browser which connects to it.  You can enter that url on
+run the tests on any browser which connects to it. You can enter that url on
 multiple browsers at once to have it run the tests on each in parallel.
 
 While karma is running, any changes you make will instantly trigger a recompile
 and retest of the entire test suite, so you can see instantly if you've broken
-a test with your changes.  You can use [jasmine focused][jasmine-focus] or
+a test with your changes. You can use [jasmine focused][jasmine-focus] or
 excluded tests (with `fdescribe` or `xdescribe`) to get karma to run only the
 tests you want while you're working on a specific feature, but make sure to
 remove these directives when you commit your code.
 
+It is also possible to only run karma on specific folders or files by filtering
+the run tests via the argument `--filter-spec` or short `-f`:
+
+```bash
+# Run all files
+yarn karma-start
+# Run specific spec files
+yarn karma-start --filter-spec profile/account/components/update_username_spec.js
+# Run specific spec folder
+yarn karma-start --filter-spec profile/account/components/
+# Run all specs which path contain vue_shared or vie
+yarn karma-start -f vue_shared -f vue_mr_widget
+```
+
 ## RSpec feature integration tests
 
 Information on setting up and running RSpec integration tests with
@@ -176,7 +190,7 @@ Information on setting up and running RSpec integration tests with
 
 Similar errors will be thrown if you're using JavaScript features not yet
 supported by the PhantomJS test runner which is used for both Karma and RSpec
-tests.  We polyfill some JavaScript objects for older browsers, but some
+tests. We polyfill some JavaScript objects for older browsers, but some
 features are still unavailable:
 
 - Array.from
@@ -188,7 +202,7 @@ features are still unavailable:
 - Symbol/Symbol.iterator
 - Spread
 
-Until these are polyfilled appropriately, they should not be used.  Please
+Until these are polyfilled appropriately, they should not be used. Please
 update this list with additional unsupported features.
 
 ### RSpec errors due to JavaScript
@@ -223,7 +237,7 @@ end
 ### Spinach errors due to missing JavaScript
 
 NOTE: **Note:** Since we are discouraging the use of Spinach when writing new
-feature tests, you shouldn't ever need to use this.  This information is kept
+feature tests, you shouldn't ever need to use this. This information is kept
 available for legacy purposes only.
 
 In Spinach, the JavaScript driver is enabled differently. In the `*.feature`