Merge branch 'docs/ssot_repository' into 'master'

Changes to Repository docs for SSOT epic

See merge request gitlab-org/gitlab-ce!31075

6 files changed, 151 insertions, 69 deletions

diff --git a/doc/user/project/repository/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png
index 52d5c518c45..52d5c518c45 100644
--- a/doc/user/project/repository/img/compare_branches.png
+++ b/doc/user/project/repository/branches/img/compare_branches.png
diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md
index a81c9197ec1..0858e8b2624 100644
--- a/doc/user/project/repository/branches/index.md
+++ b/doc/user/project/repository/branches/index.md
@@ -1,17 +1,41 @@
+---
+type: concepts, howto
+---
+
 # Branches
 
-Read through GiLab's branching documentation:
+A branch is a version of a project's working tree. You create a branch for each
+set of related changes you make. This keeps each set of changes separate from
+each other, allowing changes to be made in parallel, without affecting each
+other.
+
+After pushing your changes to a new branch, you can:
+
+- Create a [merge request](../../merge_requests/index.md)
+- Perform inline code review
+- [Discuss](../../discussions/index.md) your implementation with your team
+- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md).
+
+With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
+[approval](../../merge_requests/merge_request_approvals.md) from your managers.
+
+For more information on managing branches using the GitLab UI, see:
+
+- [Default branches](#default-branch)
+- [Create a branch](../web_editor.md#create-a-new-branch)
+- [Protected branches](../../protected_branches.md#protected-branches)
+- [Delete merged branches](#delete-merged-branches)
+- [Branch filter search box](#branch-filter-search-box)
+
+You can also manage branches using the
+[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch).
 
-- [Create a branch](../web_editor.md#create-a-new-branch).
-- [Default branch](#default-branch).
-- [Protected branches](../../protected_branches.md#protected-branches).
-- [Delete merged branches](#delete-merged-branches).
-- [Branch filter search box](#branch-filter-search-box).
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE).
 
 See also:
 
 - [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API.
-- [GitLab Flow](../../../../university/training/gitlab_flow.md). Use the best of GitLab for your branching strategies.
+- [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation.
 - [Getting started with Git](../../../../topics/git/index.md) and GitLab.
 
 ## Default branch
@@ -29,6 +53,17 @@ The default branch is also protected against accidental deletion. Read through
 the documentation on [protected branches](../../protected_branches.md#protected-branches)
 to learn more.
 
+## Compare
+
+To compare branches in a repository:
+
+1. Navigate to your project's repository.
+1. Select **Repository > Compare** in the sidebar.
+1. Select branches to compare using the [branch filter search box](#branch-filter-search-box)
+1. Click **Compare** to view the changes inline:
+
+![compare branches](img/compare_branches.png)
+
 ## Delete merged branches
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449) in GitLab 8.14.
@@ -57,3 +92,15 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi
 
 - `^feature` will only match branch names that begin with 'feature'.
 - `feature$` will only match branch names that end with 'feature'.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md
index 3b0a045ef9c..b929c6a681a 100644
--- a/doc/user/project/repository/gpg_signed_commits/index.md
+++ b/doc/user/project/repository/gpg_signed_commits/index.md
@@ -1,38 +1,39 @@
-# Signing commits with GPG
+---
+type: concepts, howto
+---
 
-NOTE: **Note:**
-The term GPG is used for all OpenPGP/PGP/GPG related material and
-implementations.
+# Signing commits with GPG
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546) in GitLab 9.5.
 > - Subkeys support was added in GitLab 10.1.
 
-GitLab can show whether a commit is verified or not when signed with a GPG key.
-All you need to do is upload the public GPG key in your profile settings.
+You can use a GPG key to sign Git commits made in a GitLab repository. Signed
+commits are labeled **Verified** if the identity of the committer can be
+verified. To verify the identity of a committer, GitLab requires their public
+GPG key.
 
-GPG verified tags are not supported yet.
+NOTE: **Note:**
+The term GPG is used for all OpenPGP/PGP/GPG related material and
+implementations.
 
-## Getting started with GPG
+GPG verified tags are not supported yet.
 
-Here are a few guides to get you started with GPG:
-
-- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
-- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
-- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
-- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
+See the [further reading](#further-reading) section for more details on GPG.
 
 ## How GitLab handles GPG
 
 GitLab uses its own keyring to verify the GPG signature. It does not access any
 public key server.
 
-In order to have a commit verified on GitLab the corresponding public key needs
-to be uploaded to GitLab. For a signature to be verified three conditions need
-to be met:
+For a commit to be verified by GitLab:
 
-1. The public key needs to be added your GitLab account
-1. One of the emails in the GPG key matches a **verified** email address you use in GitLab
-1. The committer's email matches the verified email from the gpg key
+- The committer must have a GPG public/private key pair.
+- The committer's public key must have been uploaded to their GitLab
+  account.
+- One of the emails in the GPG key must match a **verified** email address
+  used by the committer in GitLab.
+- The committer's email address must match the verified email address from the
+  GPG key.
 
 ## Generating a GPG key
 
@@ -65,8 +66,7 @@ started:
    Your selection? 1
    ```
 
-1. The next question is key length. We recommend to choose the highest value
-   which is `4096`:
+1. The next question is key length. We recommend you choose `4096`:
 
    ```
    RSA keys may be between 1024 and 4096 bits long.
@@ -74,8 +74,8 @@ started:
    Requested keysize is 4096 bits
    ```
 
-1. Next, you need to specify the validity period of your key. This is something
-   subjective, and you can use the default value which is to never expire:
+1. Specify the validity period of your key. This is something
+   subjective, and you can use the default value, which is to never expire:
 
    ```
    Please specify how long the key should be valid.
@@ -94,9 +94,9 @@ started:
    Is this correct? (y/N) y
    ```
 
-1. Enter you real name, the email address to be associated with this key (should
-   match a verified email address you use in GitLab) and an optional comment
-   (press <kbd>Enter</kbd> to skip):
+1. Enter your real name, the email address to be associated with this key
+   (should match a verified email address you use in GitLab) and an optional
+   comment (press <kbd>Enter</kbd> to skip):
 
    ```
    GnuPG needs to construct a user ID to identify your key.
@@ -270,3 +270,24 @@ via [push rules](../../../../push_rules/push_rules.md).
 ## GPG signing API
 
 Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit).
+
+## Further reading
+
+For more details about GPG, see:
+
+- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
+- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
+- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
+- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md
index 5b5685b3418..84d63d29929 100644
--- a/doc/user/project/repository/index.md
+++ b/doc/user/project/repository/index.md
@@ -1,3 +1,7 @@
+---
+type: concepts, howto
+---
+
 # Repository
 
 A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)
@@ -111,33 +115,7 @@ GitLab.
 
 ## Branches
 
-When you submit changes in a new [branch](branches/index.md), you create a new version
-of that project's file tree. Your branch contains all the changes
-you are presenting, which are detected by Git line by line.
-
-To continue your workflow, once you pushed your changes to a new branch,
-you can create a [merge request](../merge_requests/index.md), perform
-inline code review, and [discuss](../../discussions/index.md)
-your implementation with your team.
-You can live preview changes submitted to a new branch with
-[Review Apps](../../../ci/review_apps/index.md).
-
-With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
-[approval](../merge_requests/merge_request_approvals.md) from your managers.
-
-To create, delete, and view [branches](branches/index.md) via GitLab's UI:
-
-- [Default branches](branches/index.md#default-branch)
-- [Create a branch](web_editor.md#create-a-new-branch)
-- [Protected branches](../protected_branches.md#protected-branches)
-- [Delete merged branches](branches/index.md#delete-merged-branches)
-- [Branch filter search box](branches/index.md#branch-filter-search-box)
-
-Alternatively, you can use the
-[command line](../../../gitlab-basics/start-using-git.md#create-a-branch).
-
-To learn more about branching strategies read through the
-[GitLab Flow](../../../university/training/gitlab_flow.md) documentation.
+For details, see [Branches](branches/index.md).
 
 ## Commits
 
@@ -213,14 +191,6 @@ detected, add the following to `.gitattributes` in the root of your repository.
 
 > *.proto linguist-detectable=true
 
-## Compare
-
-Select branches to compare using the [branch filter search box](branches/index.md#branch-filter-search-box), then click the **Compare** button to view the changes inline:
-
-![compare branches](img/compare_branches.png)
-
-Find it under your project's **Repository > Compare**.
-
 ## Locked files **(PREMIUM)**
 
 Use [File Locking](../file_lock.md) to
@@ -256,3 +226,15 @@ By clicking the download icon, a dropdown will open with links to download the f
   `tar`, `tar.gz`, and `tar.bz2`.
 - **Artifacts:**
   allows users to download the artifacts of the latest CI build.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md
index 7c711bc0b3b..3adf66e4b6f 100644
--- a/doc/user/project/repository/reducing_the_repo_size_using_git.md
+++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md
@@ -1,3 +1,7 @@
+---
+type: howto
+---
+
 # Reducing the repository size using Git
 
 A GitLab Enterprise Edition administrator can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md)
@@ -139,3 +143,15 @@ purposes!
    ```
 
 Your repository should now be below the size limit.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md
index 0116f0fe7ca..09a5cdabc00 100644
--- a/doc/user/project/repository/web_editor.md
+++ b/doc/user/project/repository/web_editor.md
@@ -1,3 +1,7 @@
+---
+type: howto
+---
+
 # GitLab Web Editor
 
 Sometimes it's easier to make quick changes directly from the GitLab interface
@@ -169,3 +173,15 @@ through the web editor, you can choose to use another of your linked email
 addresses from the **User Settings > Edit Profile** page.
 
 [ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->