From 482f051dc26ee35f916898af552cd9cbfd53e5bc Mon Sep 17 00:00:00 2001
From: Amy Qualls <aqualls@gitlab.com>
Date: Fri, 14 Apr 2023 21:31:57 +0000
Subject: [PATCH] Revise page in prep for new feature

Bring subheadings more in tune with expected CTRT standards.
Rename subheadings to use present tense instead of gerunds.
Clean up a lot of gunky old wording.

As part of this work, I realized an important part of the forking
instructions were captured on a more generic advanced-settings page.
I've pulled that information back into this page, where it belongs.
That page also had some forking-related troubleshooting info that
also should have been here. I reunited that troubleshooting info
here as well.
---
 app/views/projects/_remove.html.haml          |  1 -
 app/views/projects/_remove_fork.html.haml     |  1 -
 doc/development/git_object_deduplication.md   | 20 ++++----
 doc/development/interacting_components.md     |  2 +-
 doc/gitlab-basics/start-using-git.md          |  2 +-
 doc/topics/git/terminology.md                 |  2 +-
 .../project/merge_requests/confidential.md    |  2 +-
 .../merge_requests/creating_merge_requests.md |  7 ++-
 .../pages_forked_sample_project.md            |  2 +-
 .../project/repository/forking_workflow.md    | 50 +++++++++++++++----
 doc/user/project/settings/index.md            | 30 +----------
 doc/user/project/working_with_projects.md     |  2 +-
 12 files changed, 61 insertions(+), 60 deletions(-)

diff --git a/app/views/projects/_remove.html.haml b/app/views/projects/_remove.html.haml
index ed238dab4ff12..dec3199ffe15d 100644
--- a/app/views/projects/_remove.html.haml
+++ b/app/views/projects/_remove.html.haml
@@ -7,7 +7,6 @@
   %h4.danger-title= _('Delete project')
   %p
     %strong= _('Deleting the project will delete its repository and all related resources, including issues and merge requests.')
-    = link_to _('Learn more.'), help_page_path('user/project/settings/index', anchor: 'remove-a-fork-relationship'), target: '_blank', rel: 'noopener noreferrer'
   %p
     %strong= _('Deleted projects cannot be restored!')
   #js-project-delete-button{ data: { form_path: project_path(project), confirm_phrase: delete_confirm_phrase(project), is_fork: project.forked?.to_s, issues_count: number_with_delimiter(issues_count), merge_requests_count: number_with_delimiter(merge_requests_count), forks_count: number_with_delimiter(forks_count), stars_count: number_with_delimiter(project.star_count) } }
diff --git a/app/views/projects/_remove_fork.html.haml b/app/views/projects/_remove_fork.html.haml
index bfc1e77118aec..89ddfa098c8ef 100644
--- a/app/views/projects/_remove_fork.html.haml
+++ b/app/views/projects/_remove_fork.html.haml
@@ -8,5 +8,4 @@
   = form_for @project, url: remove_fork_project_path(@project), method: :delete, html: { id: remove_form_id } do |f|
     %p
       %strong= _('Once removed, the fork relationship cannot be restored. This project will no longer be able to receive or send merge requests to the source project or other forks.')
-      = link_to _('Learn more.'), help_page_path('user/project/settings/index', anchor: 'remove-a-fork-relationship'), target: '_blank', rel: 'noopener noreferrer'
     .js-confirm-danger{ data: remove_fork_project_confirm_json(@project, remove_form_id) }
diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md
index 6014ccbfb394a..e98ebe5efe13f 100644
--- a/doc/development/git_object_deduplication.md
+++ b/doc/development/git_object_deduplication.md
@@ -23,15 +23,17 @@ At the Git level, we achieve deduplication by using
 Git alternates is a mechanism that lets a repository borrow objects from
 another repository on the same machine.
 
-If we want repository A to borrow from repository B, we first write a
-path that resolves to `B.git/objects` in the special file
-`A.git/objects/info/alternates`. This establishes the alternates link.
-Next, we must perform a Git repack in A. After the repack, any objects
-that are duplicated between A and B are deleted from A. Repository
-A is now no longer self-contained, but it still has its own refs and
-configuration. Objects in A that are not in B remain in A. For this
-to work, it is of course critical that **no objects ever get deleted from
-B** because A might need them.
+To make repository A borrow from repository B:
+
+1. Establish the alternates link in the special file `A.git/objects/info/alternates`
+   by writing a path that resolves to `B.git/objects`.
+1. In repository A, run `git repack` to remove all objects in repository A that
+   also exist in repository B.
+
+After the repack, repository A is no longer self-contained, but still contains its
+own refs and configuration. Objects in A that are not in B remain in A. For this
+configuration to work, **objects must not be deleted from repository B** because
+repository A might need them.
 
 WARNING:
 Do not run `git prune` or `git gc` in object pool repositories, which are
diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md
index f4becd062458a..7fb711795c1eb 100644
--- a/doc/development/interacting_components.md
+++ b/doc/development/interacting_components.md
@@ -29,5 +29,5 @@ See also [File Storage in GitLab](file_storage.md).
 ### Forks
 
 GitLab supports a great amount of features for [merge requests](../user/project/merge_requests/index.md). One
-of them is the ability to create merge requests from and to [forks](../user/project/repository/forking_workflow.md#creating-a-fork),
+of them is the ability to create merge requests from and to [forks](../user/project/repository/forking_workflow.md#create-a-fork),
 which should also be highly considered and tested upon development phase.
diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md
index 194647259b8f7..5fcaa68656f9d 100644
--- a/doc/gitlab-basics/start-using-git.md
+++ b/doc/gitlab-basics/start-using-git.md
@@ -103,7 +103,7 @@ To use the repository in the examples on this page:
 
 The project becomes available at `https://gitlab.com/<your-namespace>/sample-project/`.
 
-You can [fork](../user/project/repository/forking_workflow.md#creating-a-fork) any project you have access to.
+You can [fork](../user/project/repository/forking_workflow.md#create-a-fork) any project you have access to.
 
 ## Clone a repository
 
diff --git a/doc/topics/git/terminology.md b/doc/topics/git/terminology.md
index 8b1db5b4416d6..cef9b7cc35b9b 100644
--- a/doc/topics/git/terminology.md
+++ b/doc/topics/git/terminology.md
@@ -27,7 +27,7 @@ In GitLab, a repository is contained in a **project**.
 ## Fork
 
 When you want to contribute to someone else's repository, you make a copy of it.
-This copy is called a [**fork**](../../user/project/repository/forking_workflow.md#creating-a-fork).
+This copy is called a [**fork**](../../user/project/repository/forking_workflow.md#create-a-fork).
 The process is called "creating a fork."
 
 When you fork a repository, you create a copy of the project in your own
diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md
index 307998f697d69..edcc5711b98ea 100644
--- a/doc/user/project/merge_requests/confidential.md
+++ b/doc/user/project/merge_requests/confidential.md
@@ -65,7 +65,7 @@ Your branch, merge requests, and commits remain in your private fork. This preve
 prematurely revealing confidential information.
 
 Open a merge request
-[from your fork to the upstream repository](../repository/forking_workflow.md#merging-upstream) when:
+[from your fork to the upstream repository](../repository/forking_workflow.md#merge-changes-back-upstream) when:
 
 - You are satisfied the problem is resolved in your private fork.
 - You are ready to make the confidential commits public.
diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md
index 2043bf16af902..8a4a61bb80d90 100644
--- a/doc/user/project/merge_requests/creating_merge_requests.md
+++ b/doc/user/project/merge_requests/creating_merge_requests.md
@@ -50,7 +50,7 @@ instead of immediately creating the merge request.
 - Your project is private and the issue is confidential.
 
 To make this button appear, one possible workaround is to
-[remove your project's fork relationship](../settings/index.md#remove-a-fork-relationship).
+[remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork).
 After removal, the fork relationship cannot be restored. This project can no longer
 be able to receive or send merge requests to the source project, or other forks.
 
@@ -151,9 +151,8 @@ You can create a merge request from your fork to contribute back to the main pro
 1. Select **Create merge request**.
 
 After your work is merged, if you don't intend to
-make any other contributions to the upstream project, you can unlink your
-fork from its upstream project. Go to **Settings > Advanced Settings** and
-[remove the forking relationship](../settings/index.md#remove-a-fork-relationship).
+make any other contributions to the upstream project, you can
+[unlink your fork](../repository/forking_workflow.md#unlink-a-fork) from its upstream project.
 
 For more information, [see the forking workflow documentation](../repository/forking_workflow.md).
 
diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md
index 35e751a3a6d5d..e8de80ac13748 100644
--- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md
+++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md
@@ -18,7 +18,7 @@ configured to generate a Pages site.
 To fork a sample project and create a Pages website:
 
 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group.
-1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork).
+1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#create-a-fork).
 1. In the upper-right corner, select **Fork**, then choose a namespace to fork to.
 1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**.
    GitLab CI/CD builds and deploys your site.
diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md
index 85414a55e8194..423bdd178c6c4 100644
--- a/doc/user/project/repository/forking_workflow.md
+++ b/doc/user/project/repository/forking_workflow.md
@@ -15,7 +15,7 @@ A fork is a personal copy of the repository and all its branches, which you crea
 in a namespace of your choice. Make changes in your own fork and
 submit them through a merge request to the repository you don't have access to.
 
-## Creating a fork
+## Create a fork
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) a new form in GitLab 13.11 [with a flag](../../../user/feature_flags.md) named `fork_project_form`. Disabled by default.
 > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77181) in GitLab 14.8. Feature flag `fork_project_form` removed.
@@ -39,7 +39,7 @@ GitLab creates your fork, and redirects you to the new fork's page.
 ## Update your fork
 
 To copy the latest changes from the upstream repository into your fork, update it
-[from the command line](#from-the-command-line). GitLab Premium and higher tiers can also
+from the command line. GitLab Premium and higher tiers can also
 [configure forks as pull mirrors](#with-repository-mirroring)
 of the upstream repository.
 
@@ -113,7 +113,7 @@ For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull-
 WARNING:
 With mirroring, before approving a merge request, you are asked to sync. You should automate it.
 
-## Merging upstream
+## Merge changes back upstream
 
 When you are ready to send your code back to the upstream project,
 [create a merge request](../merge_requests/creating_merge_requests.md). For **Source branch**,
@@ -128,15 +128,33 @@ Then you can add labels, a milestone, and assign the merge request to someone wh
 your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your
 changes are added to the repository and branch you're merging into.
 
-## Removing a fork relationship
+## Unlink a fork
 
-You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#remove-a-fork-relationship).
+Removing a fork relationship unlinks your fork from its upstream project.
+Your fork then becomes an independent project.
 
-If you unlink a fork in this way and if [pool repositories](../../../development/git_object_deduplication.md#pool-repositories) are used, all objects are
-copied from the pool into the fork.
+Prerequisites:
 
-After this copy is complete, the relationship is broken and the fork becomes an independent project. From this point, any updates to objects in the pool are
-not propagated to the project that was previously a fork.
+- You must be a project owner to unlink a fork.
+
+WARNING:
+If you remove a fork relationship, you can't send merge requests to the source.
+If anyone has forked your project, their fork also loses the relationship.
+To restore the fork relationship, [use the API](../../../api/projects.md#create-a-forked-fromto-relation-between-existing-projects).
+
+To remove a fork relationship:
+
+1. On the top bar, select **Main menu > Projects** and find your project.
+1. On the left sidebar, select **Settings > General**.
+1. Expand **Advanced**.
+1. In the **Remove fork relationship** section, select **Remove fork relationship**.
+1. To confirm, enter the project path and select **Confirm**.
+
+When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_types.md#hashed-object-pools)
+to share objects with another repository:
+
+- All objects are copied from the pool into your fork.
+- After the copy process completes, no further updates from the storage pool are propagated to your fork.
 
 ## Related topics
 
@@ -145,8 +163,20 @@ not propagated to the project that was previously a fork.
 
 ## Troubleshooting
 
-### An error occurred while forking the project. Please try again
+### Error: `An error occurred while forking the project. Please try again`
 
 This error can be due to a mismatch in shared runner settings between the forked project
 and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks)
 in the Runner documentation for more information.
+
+### Removing fork relationship fails
+
+If removing the fork through the UI or API is not working, you can attempt the
+fork relationship removal in a
+[Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session):
+
+```ruby
+p = Project.find_by_full_path('<project_path>')
+u = User.find_by_username('<username>')
+Projects::UnlinkForkService.new(p, u).execute
+```
diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md
index 3ead11d3a9e60..5023ff36163c8 100644
--- a/doc/user/project/settings/index.md
+++ b/doc/user/project/settings/index.md
@@ -175,7 +175,7 @@ Learn how to [export a project](import_export.md#import-a-project-and-its-data)
 ## Advanced project settings
 
 Use the advanced settings to archive, rename, transfer,
-remove a fork relationship, or delete a project.
+[remove a fork relationship](../repository/forking_workflow.md#unlink-a-fork), or delete a project.
 
 ### Archive a project
 
@@ -348,24 +348,6 @@ To restore a project marked for deletion:
 1. Navigate to your project, and select **Settings > General > Advanced**.
 1. In the Restore project section, select **Restore project**.
 
-## Remove a fork relationship
-
-Prerequisites:
-
-- You must be a project owner to remove a fork relationship.
-
-WARNING:
-If you remove a fork relationship, you can't send merge requests to the source. If anyone has forked your project, their fork also loses the relationship.
-To restore the fork relationship, [use the API](../../../api/projects.md#create-a-forked-fromto-relation-between-existing-projects).
-
-To remove a fork relationship:
-
-1. On the top bar, select **Main menu > Projects** and find your project.
-1. On the left sidebar, select **Settings > General**.
-1. Expand **Advanced**.
-1. In the **Remove fork relationship** section, select **Remove fork relationship**.
-1. To confirm, enter the project path and select **Confirm**.
-
 ## Monitor settings
 
 ### Alerts
@@ -399,16 +381,6 @@ to enable the syncing of public Issues to a [deployed status page](../../../oper
 
 When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks.
 
-### Remove a fork relationship through console
-
-If removing the fork through the UI or API is not working, you can attempt the fork relationship removal in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session).
-
-```ruby
-p = Project.find_by_full_path('<project_path>')
-u = User.find_by_username('<username>')
-Projects::UnlinkForkService.new(p, u).execute
-```
-
 ### Transfer a project through console
 
 If transferring a project through the UI or API is not working, you can attempt the transfer in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session).
diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md
index 24ca86fc93b13..69087791a3e0d 100644
--- a/doc/user/project/working_with_projects.md
+++ b/doc/user/project/working_with_projects.md
@@ -328,7 +328,7 @@ download starts, the `insteadOf` configuration sends the traffic to the secondar
 
 - [Import a project](../../user/project/import/index.md).
 - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md).
-- [Fork a project](repository/forking_workflow.md#creating-a-fork).
+- [Fork a project](repository/forking_workflow.md#create-a-fork).
 - [Adjust project visibility and access levels](settings/index.md#configure-project-visibility-features-and-permissions).
 - [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names)
 
-- 
GitLab