Merge branch 'docs-migration-edits' into 'master'

Edits to migration docs

See merge request gitlab-org/gitlab!61192

doc/user/project/import/bitbucket.md

@@ -14,26 +14,27 @@ Server (aka Stash). If you are trying to import projects from Bitbucket Server,
 
 Import your projects from Bitbucket Cloud to GitLab with minimal effort.
 
-## Overview
-
-- At its current state, the Bitbucket importer can import:
-  - the repository description (GitLab 7.7+)
-  - the Git repository data (GitLab 7.7+)
-  - the issues (GitLab 7.7+)
-  - the issue comments (GitLab 8.15+)
-  - the pull requests (GitLab 8.4+)
-  - the pull request comments (GitLab 8.15+)
-  - the milestones (GitLab 8.15+)
-  - the wiki (GitLab 8.15+)
-- References to pull requests and issues are preserved (GitLab 8.7+)
-- Repository public access is retained. If a repository is private in Bitbucket
-  it will be created as private in GitLab as well.
+The Bitbucket importer can import:
+
+- Repository description (GitLab 7.7+)
+- Git repository data (GitLab 7.7+)
+- Issues (GitLab 7.7+)
+- Issue comments (GitLab 8.15+)
+- Pull requests (GitLab 8.4+)
+- Pull request comments (GitLab 8.15+)
+- Milestones (GitLab 8.15+)
+- Wiki (GitLab 8.15+)
+
+When importing:
+
+- References to pull requests and issues are preserved (GitLab 8.7+).
+- Repository public access is retained. If a repository is private in Bitbucket, it's created as
+  private in GitLab as well.
 
 ## Requirements
 
-The [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be first enabled in order to be
-able to import your projects from Bitbucket Cloud. Ask your GitLab administrator
-to enable this if not already.
+To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md)
+must be enabled. Ask your GitLab administrator to enable this if it isn't already enabled.
 
 ## How it works
 

doc/user/project/import/bitbucket_server.md

@@ -15,31 +15,31 @@ Use the [Bitbucket Cloud importer](bitbucket.md) for that.
 
 Import your projects from Bitbucket Server to GitLab with minimal effort.
 
-## Overview
+The Bitbucket importer can import:
 
-- In its current state, the Bitbucket importer can import:
-  - the repository description (GitLab 11.2+)
-  - the Git repository data (GitLab 11.2+)
-  - the pull requests (GitLab 11.2+)
-  - the pull request comments (GitLab 11.2+)
-- Repository public access is retained. If a repository is private in Bitbucket
-  it will be created as private in GitLab as well.
+- Repository description (GitLab 11.2+)
+- Git repository data (GitLab 11.2+)
+- Pull requests (GitLab 11.2+)
+- Pull request comments (GitLab 11.2+)
+
+When importing:
+
+- Repository public access is retained. If a repository is private in Bitbucket, it's created as
+  private in GitLab as well.
 
 ## Limitations
 
-1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any
-   Bitbucket comments out of bounds are inserted as comments in the merge
-   request.
-1. Bitbucket Server allows multiple levels of threading. GitLab import
-   collapses this into one thread and quote part of the original comment.
-1. Declined pull requests have unreachable commits, which prevents the GitLab
-   importer from generating a proper diff. These pull requests show up as
-   empty changes.
-1. Attachments in Markdown are currently not imported.
-1. Task lists are not imported.
-1. Emoji reactions are not imported
-1. Project filtering does not support fuzzy search (only `starts with` or `full
-   match strings` are currently supported)
+- GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds
+  are inserted as comments in the merge request.
+- Bitbucket Server allows multiple levels of threading. GitLab import collapses this into one thread
+  and quote part of the original comment.
+- Declined pull requests have unreachable commits, which prevents the GitLab importer from
+  generating a proper diff. These pull requests show up as empty changes.
+- Attachments in Markdown are not imported.
+- Task lists are not imported.
+- Emoji reactions are not imported.
+- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are 
+  supported).
 
 ## How it works
 
@@ -104,7 +104,7 @@ To disable it:
 Feature.disable(:bitbucket_server_user_mapping_by_username)
 ```
 
-## Importing your Bitbucket repositories
+## Import your Bitbucket repositories
 
 1. Sign in to GitLab and go to your dashboard.
 1. Click on **New project**.

doc/user/project/import/fogbugz.md

@@ -8,12 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Import your project from FogBugz to GitLab
 
 It only takes a few simple steps to import your project from FogBugz.
-The importer will import all of your cases and comments with original case
-numbers and timestamps. You will also have the opportunity to map FogBugz
-users to GitLab users.
+The importer imports all your cases and comments with original case
+numbers and timestamps. You can also map FogBugz users to GitLab users.
 
-1. From your GitLab dashboard click 'New project'
-1. Click on the 'FogBugz' button
+Follow these steps to import your project from FogBugz:
+
+1. From your GitLab dashboard, select **New project**.
+
+1. Select the **FogBugz** button.
 
   ![FogBugz](img/fogbugz_import_select_fogbogz.png)
 
@@ -25,11 +27,11 @@ users to GitLab users.
 
   ![User Map](img/fogbugz_import_user_map.png)
 
-1. Select the projects you wish to import by clicking the Import buttons
+1. Select the projects you wish to import by selecting the **Import** buttons.
 
   ![Import Project](img/fogbugz_import_select_project.png)
 
-1. Once the import has finished click the link to take you to the project
+1. Once the import finishes, click the link to go to the project
    dashboard. Follow the directions to push your existing repository.
 
   ![Finished](img/fogbugz_import_finished.png)

doc/user/project/import/gitea.md

@@ -9,20 +9,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 Import your projects from Gitea to GitLab with minimal effort.
 
-## Overview
-
 NOTE:
 This requires Gitea `v1.0.0` or newer.
 
-- At its current state, Gitea importer can import:
-  - the repository description (GitLab 8.15+)
-  - the Git repository data (GitLab 8.15+)
-  - the issues (GitLab 8.15+)
-  - the pull requests (GitLab 8.15+)
-  - the milestones (GitLab 8.15+)
-  - the labels (GitLab 8.15+)
-- Repository public access is retained. If a repository is private in Gitea
-  it will be created as private in GitLab as well.
+The Gitea importer can import:
+
+- Repository description (GitLab 8.15+)
+- Git repository data (GitLab 8.15+)
+- Issues (GitLab 8.15+)
+- Pull requests (GitLab 8.15+)
+- Milestones (GitLab 8.15+)
+- Labels (GitLab 8.15+)
+
+When importing:
+
+- Repository public access is retained. If a repository is private in Gitea it's created as private
+  in GitLab as well.
 
 ## How it works
 
@@ -35,13 +37,13 @@ The importer creates any new namespaces (groups) if they don't exist or in
 the case the namespace is taken, the repository is imported under the user's
 namespace that started the import process.
 
-## Importing your Gitea repositories
+## Import your Gitea repositories
 
 The importer page is visible when you create a new project.
 
 ![New project page on GitLab](img/import_projects_from_new_project_page.png)
 
-Click on the **Gitea** link and the import authorization process starts.
+Click the **Gitea** link and the import authorization process starts.
 
 ![New Gitea project import](img/import_projects_from_gitea_new_import.png)
 

doc/user/project/import/github.md

@@ -10,8 +10,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 Using the importer, you can import your GitHub repositories to GitLab.com or to
 your self-managed GitLab instance.
 
-## Overview
-
 The following aspects of a project are imported:
 
 - Repository description (GitLab.com & 7.7+)
@@ -37,12 +35,12 @@ The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `git
 
 This process does not migrate or import any types of groups or organizations from GitHub to GitLab.
 
-### Use cases
+## Use cases
 
 The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance.
 
 - If you're importing to GitLab.com, you can alternatively import GitHub repositories
-  using a [personal access token](#using-a-github-token). We do not recommend
+  using a [personal access token](#use-a-github-token). We do not recommend
   this method, as it does not associate all user activity (such as issues and
   pull requests) with matching GitLab users.
 - If you're importing to a self-managed GitLab instance, you can alternatively use the
@@ -93,7 +91,7 @@ For an overview of the import process, see the video [Migrating from GitHub to G
 
 ## Import your GitHub repository into GitLab
 
-### Using the GitHub integration
+### Use the GitHub integration
 
 Before you begin, ensure that any GitHub users who you want to map to GitLab users have either:
 
@@ -112,9 +110,9 @@ If you are using a self-managed GitLab instance or if you are importing from Git
 1. Select the **Import project** tab and then select **GitHub**.
 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application.
 1. Click **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed.
-1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import).
+1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import).
 
-### Using a GitHub token
+### Use a GitHub token
 
 NOTE:
 Using a personal access token to import projects is not recommended. If you are a GitLab.com user,
@@ -122,7 +120,7 @@ you can use a personal access token to import your project from GitHub, but this
 associate all user activity (such as issues and pull requests) with matching GitLab users.
 If you are an administrator of a self-managed GitLab instance or if you are importing from
 GitHub Enterprise, you cannot use a personal access token.
-The [GitHub integration method (above)](#using-the-github-integration) is recommended for all users.
+The [GitHub integration method (above)](#use-the-github-integration) is recommended for all users.
 Read more in the [How it works](#how-it-works) section.
 
 If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories:
@@ -136,7 +134,7 @@ If you are not using the GitHub integration, you can still perform an authorizat
 1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information.
    Once done, you'll be taken to the importer page to select the repositories to import.
 
-### Selecting which repositories to import
+### Select which repositories to import
 
 After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and
 your GitHub repositories are listed.
@@ -162,7 +160,7 @@ Additionally, you can configure GitLab to send pipeline status updates back GitH
 If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both
 of the above are automatically configured. **(PREMIUM)**
 
-## Improving the speed of imports on self-managed instances
+## Improve the speed of imports on self-managed instances
 
 NOTE:
 Administrator access to the GitLab server is required.

doc/user/project/import/jira.md

@@ -54,13 +54,13 @@ Make sure you have the integration set up before trying to import Jira issues.
 
 > New import form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216145) in GitLab 13.2.
 
-To import Jira issues to a GitLab project, follow the steps below.
-
 NOTE:
 Importing Jira issues is done as an asynchronous background job, which
 may result in delays based on import queues load, system load, or other factors.
 Importing large projects may take several minutes depending on the size of the import.
 
+To import Jira issues to a GitLab project, follow these steps:
+
 1. On the **{issues}** **Issues** page, click **Import Issues** (**{import}**) **> Import from Jira**.
 
    ![Import issues from Jira button](img/jira/import_issues_from_jira_button_v12_10.png)

doc/user/project/import/manifest.md

@@ -49,9 +49,9 @@ As a result, the following projects are created:
 | `https://gitlab.com/YOUR_GROUP/build/make`      | <https://android.googlesource.com/platform/build>           |
 | `https://gitlab.com/YOUR_GROUP/build/blueprint` | <https://android.googlesource.com/platform/build/blueprint> |
 
-## Importing the repositories
+## Import the repositories
 
-You can start the import with:
+Follow these steps to start the import:
 
 1. From your GitLab dashboard click **New project**
 1. Switch to the **Import project** tab

doc/user/project/import/phabricator.md

@@ -20,7 +20,7 @@ GitLab allows you to import all tasks from a Phabricator instance into
 GitLab issues. The import creates a single project with the
 repository disabled.
 
-Currently, only the following basic fields are imported:
+Only the following basic fields are imported:
 
 - Title
 - Description
@@ -34,6 +34,6 @@ The assignee and author of a user are deducted from a Task's owner and
 author: If a user with the same username has access to the namespace
 of the project being imported into, then the user will be linked.
 
-## Enabling this feature
+## Enable this feature
 
 Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area.

doc/user/project/import/svn.md

@@ -11,18 +11,16 @@ Subversion (SVN) is a central version control system (VCS) while
 Git is a distributed version control system. There are some major differences
 between the two, for more information consult your favorite search engine.
 
-## Overview
-
 There are two approaches to SVN to Git migration:
 
-1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which:
-   - Makes the GitLab repository to mirror the SVN project.
-   - Git and SVN repositories are kept in sync; you can use either one.
-   - Smoothens the migration process and allows to manage migration risks.
+- [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which:
+  - Makes the GitLab repository to mirror the SVN project.
+  - Git and SVN repositories are kept in sync; you can use either one.
+  - Smoothens the migration process and allows to manage migration risks.
 
-1. [Cut over migration](#cut-over-migration-with-svn2git) which:
-   - Translates and imports the existing data and history from SVN to Git.
-   - Is a fire and forget approach, good for smaller teams.
+- [Cut over migration](#cut-over-migration-with-svn2git) which:
+  - Translates and imports the existing data and history from SVN to Git.
+  - Is a fire and forget approach, good for smaller teams.
 
 ## Smooth migration with a Git/SVN mirror using SubGit
 

doc/user/project/import/tfvc.md

@@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: concepts
 ---
 
-# Migrating from TFVC to Git
+# Migrate from TFVC to Git
 
 Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/)
 in 2019, is a set of tools developed by Microsoft which also includes
@@ -48,10 +48,10 @@ Migration options from TFVC to Git depend on your operating system.
 
 - If you're migrating on Microsoft Windows:
 
-  Use the [`git-tfs`](https://github.com/git-tfs/git-tfs)
-tool.
-  Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) guide for details.
+  - Use the [`git-tfs`](https://github.com/git-tfs/git-tfs)
+    tool. See [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md)
+    for details.
 
 - If you're on a Unix-based system:
 
-  Follow the procedures described with this [TFVC to Git migration tool](https://github.com/turbo/gtfotfs).
+  - Follow the procedures described with this [TFVC to Git migration tool](https://github.com/turbo/gtfotfs).