Merge branch 'docs-ctrt-bitbucket-server' into 'master'

CTRT revisions for Bitbucket Server import doc

See merge request gitlab-org/gitlab!79691

doc/user/project/import/bitbucket_server.md

@@ -5,126 +5,102 @@ group: Import
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Import your project from Bitbucket Server to GitLab **(FREE)**
+# Import your project from Bitbucket Server **(FREE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2.
 
 NOTE:
-The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org).
-Use the [Bitbucket Cloud importer](bitbucket.md) for that.
+This process is different than [importing from Bitbucket Cloud](bitbucket.md).
 
-Import your projects from Bitbucket Server to GitLab with minimal effort.
+From Bitbucket Server, you can import:
 
-The Bitbucket importer can import:
-
-- Repository description (GitLab 11.2+)
-- Git repository data (GitLab 11.2+)
-- Pull requests (GitLab 11.2+)
-- Pull request comments (GitLab 11.2+)
+- Repository description
+- Git repository data
+- Pull requests
+- Pull request comments
 
 When importing, repository public access is retained. If a repository is private in Bitbucket, it's
 created as private in GitLab as well.
 
-## Limitations
-
-- 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.
-- Pull request approvals are not imported.
-- 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
-
-The Bitbucket Server importer works as follows:
-
-1. The user is prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket.
-   These credentials are preserved only as long as the importer is running.
-1. The importer attempts to list all the current repositories on the Bitbucket Server.
-1. Upon selection, the importer clones the repository and import pull requests and comments.
-
-### User assignment
+## Import your Bitbucket repositories
 
-When issues/pull requests are being imported, the Bitbucket importer tries to
-find the author's email address with a confirmed email address in the GitLab
-user database. If no such user is available, the project creator is set as
-the author. The importer appends a note in the comment to mark the original
-creator.
+Prerequisites:
 
-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.
+- An administrator must have enabled the **Bitbucket Server** in
+  **Admin > Settings > General > Visibility and access controls > Import sources**.
+- Review the importer's [limitations](#limitations).
 
-#### User assignment by username
+To import your Bitbucket repositories:
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4.
-> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default.
-> - It's disabled on GitLab.com.
-> - It's not recommended for production use.
-> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it.
+1. Sign in to GitLab.
+1. On the top bar, select **New** (**{plus}**).
+1. Select **New project/repository**.
+1. Select **Import project**.
+1. Select **Bitbucket Server**.
+1. Log in to Bitbucket and grant GitLab access to your Bitbucket account.
+1. Select the projects to import, or import all projects. You can filter projects by name and select
+   the namespace for which to import each project.
 
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
+## Limitations
 
-If you've enabled this feature, the importer tries to find a user in the GitLab user database with
-the author's:
+- GitLab doesn't allow comments on arbitrary lines of code. Any out-of-bounds Bitbucket comments are
+  inserted as comments in the merge request.
+- Bitbucket Server allows multiple threading levels. The importer collapses this into one thread and
+  quotes part of the original comment.
+- Declined pull requests have unreachable commits. This prevents the importer from generating a
+  proper diff. These pull requests show up as empty changes.
+- Project filtering doesn't support fuzzy search. Only starts with or full match strings are
+  supported.
 
-- `username`
-- `slug`
-- `displayName`
+The following aren't imported:
 
-If the user is not found by any of these properties, the project creator is set as the author.
+- Pull request approvals
+- Attachments in Markdown
+- Task lists
+- Emoji reactions
 
-##### Enable or disable User assignment by username
+## User assignment
 
-User assignment by username is under development and not ready for production use. It is
-deployed behind a feature flag that is **disabled by default**.
-[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
-can enable it.
+When issues and pull requests are importing, the importer tries to find the author's email address
+with a confirmed email address in the GitLab user database. If no such user is available, the
+project creator is set as the author. The importer appends a note in the comment to mark the
+original creator.
 
-To enable it:
+The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the
+repository imports under the namespace of the user who started the import process.
 
-```ruby
-Feature.enable(:bitbucket_server_user_mapping_by_username)
-```
+### User assignment by username
 
-To disable it:
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default.
+> - Not recommended for production use.
 
-```ruby
-Feature.disable(:bitbucket_server_user_mapping_by_username)
-```
+FLAG:
+On self-managed GitLab and GitLab.com, by default this feature is not available. To make it
+available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md)
+named `bitbucket_server_user_mapping_by_username`. This feature is not ready for production use.
 
-## Import your Bitbucket repositories
+With this feature enabled, the importer tries to find a user in the GitLab user database with the
+author's:
 
-Prerequisite:
+- `username`
+- `slug`
+- `displayName`
 
-- An administrator must have enabled the importer in
-  **Admin > Application Settings > Visibility and access controls > Import sources**.
+If no user matches these properties, the project creator is set as the author.
 
-To import your Bitbucket repositories:
+## Troubleshooting
 
-1. Sign in to GitLab.
-1. On the top bar, select **New** (**{plus}**).
-1. Select **New project/repository**.
-1. Select **Import project**.
-1. Select **Bitbucket Server**.
-1. Log in to Bitbucket and grant GitLab access to your Bitbucket account.
-1. Select the projects that you'd like to import or import all projects.
-   You can filter projects by name and select the namespace
-   each project will be imported for.
+### General
 
-## Automate group and project import **(PREMIUM)**
+If the GUI-based import tool does not work, you can try to:
 
-For information on automating user, group, and project import API calls, see
-[Automate group and project import](index.md#automate-group-and-project-import).
+- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server)
+  Bitbucket Server endpoint.
+- Set up [repository mirroring](../repository/mirror/index.md).
+  It provides verbose error output.
 
-## Troubleshooting
+See the [troubleshooting section](bitbucket.md#troubleshooting)
+for Bitbucket Cloud.
 
 ### LFS objects not imported
 
@@ -132,11 +108,7 @@ If the project import completes but LFS objects can't be downloaded or cloned, y
 password or personal access token containing special characters. For more information, see
 [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769).
 
-### General
-
-If the GUI-based import tool does not work, you can try to:
-
-- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) Bitbucket server endpoint.
-- Set up [Repository Mirroring](../repository/mirror/index.md), which provides verbose error output.
+## Related topics
 
-See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md).
+For information on automating user, group, and project import API calls, see
+[Automate group and project import](index.md#automate-group-and-project-import).