Merge branch 'master' into xterm-npmxterm-npm

4 files changed, 102 insertions, 4 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/ee_features.md b/doc/development/ee_features.md
index 3ba03d2d591..287143d6255 100644
--- a/doc/development/ee_features.md
+++ b/doc/development/ee_features.md
@@ -644,6 +644,7 @@ information on managing page-specific javascript within EE.
 To separate EE-specific styles in SCSS files, if a component you're adding styles for
 is limited to only EE, it is better to have a separate SCSS file in appropriate directory
 within `app/assets/stylesheets`.
+See [backporting changes](#backporting-changes) for instructions on how to merge changes safely.
 
 In some cases, this is not entirely possible or creating dedicated SCSS file is an overkill,
 e.g. a text style of some component is different for EE. In such cases,
@@ -683,6 +684,19 @@ to avoid conflicts during CE to EE merge.
 // EE-specific end
 ```
 
+### Backporting changes from EE to CE
+
+When working in EE-specific features, you might have to tweak a few files that are not EE-specific. Here is a workflow to make sure those changes end up backported safely into CE too.
+(This approach does not refer to changes introduced via [csslab](https://gitlab.com/gitlab-org/csslab/).)
+
+1. **Make your changes in the EE branch.** If possible, keep a separated commit (to be squashed) to help backporting and review.
+1. **Open merge request to EE project.**
+1. **Apply the changes you made to CE files in a branch of the CE project.** (Tip: Use `patch` with the diff from your commit in EE branch)
+1. **Open merge request to CE project**, referring it's a backport of EE changes and link to MR open in EE.
+1. Once EE MR is merged, the MR towards CE can be merged. **But not before**.
+
+**Note:** regarding SCSS, make sure the files living outside `/ee/` don't diverge between CE and EE projects.
+
 ## gitlab-svgs
 
 Conflicts in `app/assets/images/icons.json` or `app/assets/images/icons.svg` can
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/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