Merge branch '293646-aqualls-cherrypick' into 'master'

Revise cherry-pick page for CTRT

See merge request gitlab-org/gitlab!69326

doc/api/commits.md

@@ -289,11 +289,11 @@ Example response:
 
 ```
 
-## Cherry pick a commit
+## Cherry-pick a commit
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8047) in GitLab 8.15.
 
-Cherry picks a commit to a given branch.
+Cherry-picks a commit to a given branch.
 
 ```plaintext
 POST /projects/:id/repository/commits/:sha/cherry_pick

doc/topics/git/cherry_picking.md

@@ -5,49 +5,76 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 comments: false
 ---
 
-# Cherry pick **(FREE)**
+# Cherry-pick a Git commit **(FREE)**
 
-Given an existing commit on one branch, apply the change to another branch.
+In Git, you can *cherry-pick* a commit (a set of changes) from an existing branch,
+and apply those changes to another branch. Cherry-picks can help you:
 
-This can be useful for backporting bug fixes to previous release branches. Make
-the commit on the default branch, and then cherry pick it into the release branch.
+- Backport bug fixes from the default branch to previous release branches.
+- Copy changes from a fork
+  [to the upstream repository](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-into-a-project).
 
-## Sample workflow
+You can cherry-pick commits from the command line. In the GitLab user interface,
+you can also:
 
-1. Check out a new `stable` branch from the default branch:
+- Cherry-pick [all changes from a merge request](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-merge-request).
+- Cherry-pick [a single commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-commit).
+- Cherry-pick [from a fork to the upstream repository](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-into-a-project).
+
+## Cherry-pick from the command line
+
+These instructions explain how to cherry-pick a commit from the default branch (`main`)
+into a different branch (`stable`):
+
+1. Check out the default branch, then check out a new `stable` branch based on it:
 
    ```shell
-   git checkout master
+   git checkout main
    git checkout -b stable
    ```
 
 1. Change back to the default branch:
 
    ```shell
-   git checkout master
+   git checkout main
    ```
 
-1. Make any required changes, then commit the changes:
+1. Make your changes, then commit them:
 
    ```shell
    git add changed_file.rb
    git commit -m 'Fix bugs in changed_file.rb'
    ```
 
-1. Review the commit log and copy the SHA of the latest commit:
+1. Display the commit log:
 
    ```shell
-   git log
+   $ git log
+
+   commit 0000011111222223333344444555556666677777
+   Merge: 88888999999 aaaaabbbbbb
+   Author: user@example.com
+   Date:   Tue Aug 31 21:19:41 2021 +0000
    ```
 
-1. Check out the `stable` branch:
+1. Identify the `commit` line, and copy the string of letters and numbers on that line.
+   This information is the SHA (Secure Hash Algorithm) of the commit. The SHA is
+   a unique identifier for this commit, and you need it in a future step.
+
+1. Now that you know the SHA, check out the `stable` branch again:
 
    ```shell
    git checkout stable
    ```
 
-1. Cherry pick the commit by using the SHA copied previously:
+1. Cherry-pick the commit into the `stable` branch, and change `SHA` to your commit
+   SHA:
 
    ```shell
-   git cherry-pick <commit SHA>
+   git cherry-pick <SHA>
    ```
+
+## Related links
+
+- Cherry-pick commits with [the Commits API](../../api/commits.md#cherry-pick-a-commit)
+- Git documentation [for cherry-picks](https://git-scm.com/docs/git-cherry-pick)

doc/topics/git/index.md

@@ -58,7 +58,7 @@ The following are resources on version control concepts:
 You can do many Git tasks from the command line:
 
 - [Bisect](bisect.md).
-- [Cherry pick](cherry_picking.md).
+- [Cherry-pick](cherry_picking.md).
 - [Feature branching](feature_branching.md).
 - [Getting started with Git](getting_started.md).
 - [Git add](git_add.md).

doc/user/project/merge_requests/index.md

@@ -145,7 +145,7 @@ For a web developer writing a webpage for your company's website:
 1. You request your web designers for their implementation.
 1. You request the [approval](approvals/index.md) from your manager.
 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/).
-1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production.
+1. Your production team [cherry-picks](cherry_pick_changes.md) the merge commit into production.
 
 ## Related topics