Add latest changes from gitlab-org/gitlab@master

2 files changed, 40 insertions, 17 deletions

diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 225e3a65eab..9c4b97c4adf 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -1062,17 +1062,36 @@ a helpful link back to how the feature was developed.
   > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
   ```
 
-### Removing version text
-
-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.
+### Importance of referencing GitLab versions and tiers
+
+Mentioning GitLab versions and tiers is important to all users and contributors
+to quickly have access to the issue or merge request that
+introduced the change for reference. Also, they can easily understand what
+features they have in their GitLab instance and version, given that the note has
+some key information.
+
+`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing) 12.7`
+links to the issue that introduced the feature, says which GitLab tier it
+belongs to, says the GitLab version that it became available in, and links to
+the pricing page in case the user wants to upgrade to a paid tier
+to use that feature.
+
+For example, if I'm a regular user and I'm looking at the docs for a feature I haven't used before,
+I can immediately see if that feature is available to me or not. Alternatively,
+if I have been using a certain feature for a long time and it changed in some way,
+it's important
+to me to spot when it changed and what's new in that feature.
+
+This is even more important as we don't have a perfect process for shipping docs.
+Unfortunately, we still see features without docs and docs without
+features. So, for now, we cannot rely 100% on the docs site versions.
+
+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, you can consider removing the text if it's irrelevant or confusing.
 
 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:**
-This guidance applies to any text that mentions a GitLab version, not just "Introduced in... " text.
-Other text includes deprecation notices and version-specific how-to information.
+and older are candidates for removal if necessary for clearer or cleaner docs.
 
 ## Product badges
 
@@ -1103,6 +1122,8 @@ The tier should be ideally added to headers, so that the full badge will be disp
 However, it can be also mentioned from paragraphs, list items, and table cells. For these cases,
 the tier mention will be represented by an orange question mark that will show the tiers on hover.
 
+Use the lowest tier at the page level, even if higher-level tiers exist on the page. For example, you might have a page that is marked as Starter but a section badged as Premium.
+
 For example:
 
 - `**(STARTER)**` renders as **(STARTER)**
diff --git a/doc/development/uploads.md b/doc/development/uploads.md
index 3eda0667753..b26211901b2 100644
--- a/doc/development/uploads.md
+++ b/doc/development/uploads.md
@@ -174,14 +174,14 @@ sequenceDiagram
     c ->>+w: POST /some/url/upload
 
     w->>+s: save the incoming file on a temporary location
-    s-->>-w:  
+    s-->>-w: request result
 
     w->>+r:  POST /some/url/upload
     Note over w,r: file was replaced with its location<br>and other metadata
 
     opt requires async processing
       r->>+redis: schedule a job
-      redis-->>-r:  
+      redis-->>-r: job is scheduled
     end
 
     r-->>-c: request result
@@ -208,9 +208,11 @@ This is the more advanced acceleration technique we have in place.
 
 Workhorse asks rails for temporary pre-signed object storage URLs and directly uploads to object storage.
 
-In this setup an extra rails route needs to be implemented in order to handle authorization,
-you can see an example of this in [`Projects::LfsStorageController`](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/app/controllers/projects/lfs_storage_controller.rb)
-and [its routes](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/config/routes/git_http.rb#L31-32).
+In this setup, an extra Rails route must be implemented in order to handle authorization. Examples of this can be found in:
+
+- [`Projects::LfsStorageController`](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/app/controllers/projects/lfs_storage_controller.rb)
+  and [its routes](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/config/routes/git_http.rb#L31-32).
+- [API endpoints for uploading packages](packages.md#file-uploads).
 
 **note:** this will fallback to _disk buffered upload_ when `direct_upload` is disabled inside the [object storage setting](../administration/uploads.md#object-storage-settings).
 The answer to the `/authorize` call will only contain a file system path.
@@ -231,17 +233,17 @@ sequenceDiagram
 
     w->>+os: PUT file
     Note over w,os: file is stored on a temporary location. Rails select the destination
-    os-->>-w:  
+    os-->>-w: request result
 
     w->>+r:  POST /some/url/upload
     Note over w,r: file was replaced with its location<br>and other metadata
 
     r->>+os: move object to final destination
-    os-->>-r:  
+    os-->>-r: request result
 
     opt requires async processing
       r->>+redis: schedule a job
-      redis-->>-r:  
+      redis-->>-r: job is scheduled
     end
 
     r-->>-c: request result