Merge branch '431182-update-bitbucket-importer-docs' into 'master'

Update Bitbucket importer docs

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138295



Merged-by: Evan Read <eread@gitlab.com>
Approved-by: Evan Read <eread@gitlab.com>
Reviewed-by: Evan Read <eread@gitlab.com>
Co-authored-by: maddievn <mvanniekerk@gitlab.com>

doc/api/import.md

@@ -180,7 +180,7 @@ If you do not specify `target_namespace`, the project imports to your personal u
 
 Prerequisites:
 
-- For more information, see [prerequisites for Bitbucket Server importer](../user/project/import/bitbucket_server.md#import-your-bitbucket-repositories).
+- For more information, see [prerequisites for Bitbucket Server importer](../user/project/import/bitbucket_server.md).
 
 ```plaintext
 POST /import/bitbucket_server

doc/user/project/import/bitbucket.md

@@ -4,7 +4,7 @@ group: Import and Integrate
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Import your project from Bitbucket Cloud to GitLab **(FREE ALL)**
+# Import your project from Bitbucket Cloud **(FREE ALL)**
 
 > Parallel imports from Bitbucket Cloud [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412614) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `bitbucket_parallel_importer`. Disabled by default.
 
@@ -25,6 +25,9 @@ The Bitbucket importer can import:
 - Pull request comments
 - Milestones
 - Wiki
+- Labels
+- Milestones
+- LFS objects
 
 When importing:
 
@@ -37,12 +40,24 @@ The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.o
 Server (aka Stash). If you are trying to import projects from Bitbucket Server, use
 [the Bitbucket Server importer](bitbucket_server.md).
 
-When issues/pull requests are being imported, the Bitbucket importer uses the Bitbucket nickname of
+When issues, pull requests, and comments are imported, the Bitbucket importer uses the Bitbucket nickname of
 the author/assignee and tries to find the same Bitbucket identity in GitLab. If they don't match or
 the user is not found in the GitLab database, the project creator (most of the times the current
 user that started the import process) is set as the author, but a reference on the issue about the
 original Bitbucket author is kept.
 
+For pull requests:
+
+- If the source SHA does not exist in the repository, the importer attempts to set the source commit to the merge commit SHA.
+- The merge request assignee is set to the author. Reviewers are set with usernames matching Bitbucket identities in GitLab.
+- Approvals are not imported.
+- Merge requests in GitLab can be either can be either `opened`, `closed` or `merged`.
+
+For issues:
+
+- A label is added corresponding to the type of issue on Bitbucket. Either `bug`, `enhancement`, `proposal` or `task`.
+- If the issue on Bitbucket was one of `resolved`, `invalid`, `duplicate`, `wontfix`, or `closed`, the issue is closed on GitLab.
+
 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.

doc/user/project/import/bitbucket_server.md

@@ -6,30 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Import your project from Bitbucket Server **(FREE ALL)**
 
-> Support for pull request approval imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135256) in GitLab 16.7.
-
-NOTE:
-This process is different than [importing from Bitbucket Cloud](bitbucket.md).
-
-From Bitbucket Server, you can import:
-
-- Repository description
-- Git repository data
-- Pull requests
-- Pull request comments
-- Pull request approvals
-
-When importing, repository public access is retained. If a repository is private in Bitbucket, it's
-created as private in GitLab as well.
-
-## Import your Bitbucket repositories
-
 > - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
 > - Ability to import reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416611) in GitLab 16.3.
+> - Support for pull request approval imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135256) in GitLab 16.7.
+
+Import your projects from Bitbucket Server to GitLab.
 
-You can import Bitbucket repositories to GitLab.
+NOTE:
+This process is different than [importing from Bitbucket Cloud](bitbucket.md).
 
-### Prerequisites
+## Prerequisites
 
 > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
 
@@ -37,8 +23,9 @@ You can import Bitbucket repositories to GitLab.
   must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled
   by default on GitLab.com.
 - At least the Maintainer role on the destination group to import to.
+- Bitbucket Server authentication token with administrator access.
 
-### Import repositories
+## Import repositories
 
 To import your Bitbucket repositories:
 
@@ -53,7 +40,26 @@ To import your Bitbucket repositories:
    - For the first time: Select **Import**.
    - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project.
 
-### Items that are not imported
+## Items that are imported
+
+- Repository description
+- Git repository data
+- Pull requests
+- Pull request comments, reviewers, approvals, and merge events
+- LFS objects
+
+When importing, repository public access is retained. If a repository is private in Bitbucket, it's
+created as private in GitLab as well.
+
+When closed or merged pull requests are imported, commit SHAs that do not exist in the repository are fetched from the Bitbucket server
+to make sure pull requests have commits tied to them:
+
+- Source commit SHAs are saved with references in the format `refs/merge-requests/<iid>/head`.
+- Target commit SHAs are saved with references in the format `refs/keep-around/<SHA>`.
+
+If the source commit does not exist in the repository, a commit containing the SHA in the commit message is used instead.
+
+## Items that are not imported
 
 The following items aren't imported:
 
@@ -61,7 +67,7 @@ The following items aren't imported:
 - Task lists
 - Emoji reactions
 
-### Items that are imported but changed
+## Items that are imported but changed
 
 The following items are changed when they are imported:
 
@@ -69,7 +75,6 @@ The following items are changed when they are imported:
   inserted as comments in the merge request.
 - Multiple threading levels are collapsed into one thread and
   quotes are added as part of the original comment.
-- Declined pull requests have unreachable commits. These pull requests show up as empty changes.
 - Project filtering doesn't support fuzzy search. Only **starts with** or **full match** strings are
   supported.
 
@@ -77,10 +82,6 @@ The following items are changed when they are imported:
 
 > Importing approvals by email address or username [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23586) in GitLab 16.7.
 
-Prerequisites:
-
-- Authentication token with administrator access.
-
 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
@@ -133,16 +134,6 @@ 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).
 
-### Pull requests are missing
-
-Importing large projects spawns a process that can consume a lot of memory. Sometimes you can see messages such as `Sidekiq worker RSS out of range` in the
-[Sidekiq logs](../../../administration/logs/index.md#sidekiq-logs). This can mean that MemoryKiller is interrupting the `RepositoryImportWorker` because it's using
-too much memory.
-
-To resolve this problem, temporarily increase the `SIDEKIQ_MEMORY_KILLER_MAX_RSS` environment variable using
-[custom environment variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html) from the default `2000000` value to a larger value like `3000000`.
-Consider memory constraints on the system before deciding to increase `SIDEKIQ_MEMORY_KILLER_MAX_RSS`.
-
 ## Related topics
 
 - [Automate group and project import](index.md#automate-group-and-project-import)