Add latest changes from gitlab-org/gitlab@master

3 files changed, 75 insertions, 1 deletions

diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md
index 71963ee0c0a..d5fc24c1ddb 100644
--- a/doc/development/api_styleguide.md
+++ b/doc/development/api_styleguide.md
@@ -92,6 +92,12 @@ For instance:
 Model.create(foo: params[:foo])
 ```
 
+## Using HTTP status helpers
+
+For non-200 HTTP responses, use the provided helpers in `lib/api/helpers.rb` to ensure correct behaviour (`not_found!`, `no_content!` etc.). These will `throw` inside Grape and abort the execution of your endpoint.
+
+For `DELETE` requests, you should also generally use the `destroy_conditionally!` helper which by default returns a `204 No Content` response on success, or a `412 Precondition Failed` response if the given `If-Unmodified-Since` header is out of range. This helper calls `#destroy` on the passed resource, but you can also implement a custom deletion method by passing a block.
+
 ## Using API path helpers in GitLab Rails codebase
 
 Because we support [installing GitLab under a relative URL], one must take this
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 385569fc8fa..fd591c71e85 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -941,7 +941,7 @@ a helpful link back to how the feature was developed.
 Over time, version text will reference a progressively older version of GitLab. In cases where version text
 refers to versions of GitLab four or more major versions back, consider removing the text.
 
-For example, if the current major version is 11.x, version text referencing versions of GitLab 7.x
+For example, if the current major version is 12.x, version text referencing versions of GitLab 8.x
 and older are candidates for removal.
 
 NOTE: **Note:**
diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md
index b8101a99ff6..01ed07f8736 100644
--- a/doc/development/fe_guide/frontend_faq.md
+++ b/doc/development/fe_guide/frontend_faq.md
@@ -78,3 +78,71 @@ follow up issue and attach it to the component implementation epic found within
 
 If you are using a submit button inside a form and you attach an `onSubmit` event listener on the form element, [this piece of code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) will add a `disabled` class selector to the submit button when the form is submitted.
 To avoid this behavior, add the class `js-no-auto-disable` to the button.
+
+### 5. Should I use a full URL (i.e. `gon.gitlab_url`) or a full path (i.e. `gon.relative_url_root`) when referencing backend endpoints?
+
+It's preferred to use a **full path** over a **full URL** because the URL will use the hostname configured with
+GitLab which may not match the request. This will cause [CORS issues like this Web IDE one](https://gitlab.com/gitlab-org/gitlab/issues/36810).
+
+Example:
+
+```javascript
+// bad :(
+// If gitlab is configured with hostname `0.0.0.0`
+// This will cause CORS issues if I request from `localhost`
+axios.get(joinPaths(gon.gitlab_url, '-', 'foo'))
+
+// good :)
+axios.get(joinPaths(gon.relative_url_root, '-', 'foo'))
+```
+
+Also, please try not to hardcode paths in the Frontend, but instead receive them from the Backend (see next section).
+When referencing Backend rails paths, avoid using `*_url`, and use `*_path` instead.
+
+Example:
+
+```haml
+-# Bad :(
+#js-foo{ data: { foo_url: some_rails_foo_url } }
+
+-# Good :)
+#js-foo{ data: { foo_path: some_rails_foo_path } }
+```
+
+### 6. How should the Frontend reference Backend paths?
+
+We prefer not to add extra coupling by hardcoding paths. If possible,
+add these paths as data attributes to the DOM element being referenced in the JavaScript.
+
+Example:
+
+```javascript
+// Bad :(
+// Here's a Vuex action that hardcodes a path :(
+export const fetchFoos = ({ state }) => {
+  return axios.get(joinPaths(gon.relative_url_root, '-', 'foo'));
+};
+
+// Good :)
+function initFoo() {
+  const el = document.getElementById('js-foo');
+
+  // Path comes from our root element's data which is used to initialize the store :)
+  const store = createStore({
+    fooPath: el.dataset.fooPath
+  });
+
+  Vue.extend({
+    store,
+    el,
+    render(h) {
+      return h(Component);
+    },
+  });
+}
+
+// Vuex action can now reference the path from it's state :)
+export const fetchFoos = ({ state }) => {
+  return axios.get(state.settings.fooPath);
+};
+```