Rewrite and clarify “Adding your GitHub fork to your WP trunk copy” section for accuracy and readability

[tomdevisser]

Issue Description

The section “Adding your GitHub fork to your WP trunk copy” contains several grammatical errors, awkward phrasing, and unclear steps. It could be confusing for new contributors trying to set up their Git workflow for WordPress core development.

URL of the Page with the Issue

​https://make.wordpress.org/core/handbook/tutorials/trac/submitting-a-patch/

Section of Page with the issue

​https://make.wordpress.org/core/handbook/tutorials/trac/submitting-a-patch/#adding-your-github-fork-to-your-wp-trunk-copy

Why is this a problem?

The current wording is confusing and unprofessional. It includes broken grammar, vague instructions, and inconsistent terminology. This increases friction for new contributors and might result in incorrect Git setups or mistakes in submitting patches. This section is especially important because it’s often the first major technical step someone takes when contributing code to WordPress. If this part is unclear, it can discourage contributors before they even get started.

Suggested Fix

Rewriting the section as follows for clarity and accuracy:

Adding your GitHub fork to your WP trunk copy

To contribute via GitHub, you’ll need to fork the WordPress GitHub mirror and connect your local clone to it.

1. Create a fork of the GitHub mirror under your own GitHub account.

2. Clone your fork or connect it to your existing local clone of the WordPress development repository. Replace your-username with your GitHub username. Use the SSH or HTTPS URL depending on your setup.

git remote add fork git@github.com:your-username/wordpress-develop.git

3. Fetch all remotes to make sure you have the latest updates:

git fetch --all

4. Create a new branch to work on a specific Trac ticket. Never work directly on trunk or master.

git checkout -b 44722 fork/trunk

5. Alternatively, if you’re checking out an existing branch from your fork:

git checkout fork/44722

6. Make your code changes, commit them, and push to your fork.

git push fork 44722

7. Go to your fork on GitHub. If your GitHub account is linked to your WordPress.org profile, GitHub will prompt you to open a Pull Request. Make sure the title includes the Trac ticket number (e.g., #44722: Fix X issue in Y component).

For more details on GitHub integration, see the GitHub Pull Requests for Code Review documentation (​https://make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/).

[psykro]

Putting my hand up to work on this next week, if someone triaging this could assign it to me, as I can't seem to self-assign. Thanks

[psykro]

@tomd6r I was reviewing your suggested change today, could I confirm something in this section

Clone your fork or connect it to your existing local clone of the WordPress development repository. Replace your-username with your GitHub username. Use the SSH or HTTPS URL depending on your setup.

git remote add fork git@github.com:your-username/wordpress-develop.git

I assume the git remote add command here is if you have cloned the original WordPress/wordpress-develop repository by mistake, instead of first forking it, and then cloning your fork?

[tomdevisser]

I assume the git remote add command here is if you have cloned the original WordPress/wordpress-develop repository by mistake, instead of first forking it, and then cloning your fork?

@psykro Good question! Yes — the git remote add fork command is helpful if you’ve cloned the upstream repo by mistake and need to push changes to your own fork. But it’s also useful more generally — for example, if you’re working from an existing clone (regardless of how it was set up) and want to add your fork as a remote to contribute via GitHub.

We could clarify that by updating the wording to something like:

---

If you cloned wordpress/wordpress-develop, or already have a local clone without your fork as a remote, you can add it like this to push your changes:

git remote add fork git@github.com:your-username/wordpress-develop.git

Let me know what you think!

[psykro]

@tomd6r got it, thank you.

I'm going to rework the suggested steps slightly, to also allow for someone who has forked from the word go, as the minimum commands there differ slightly. Basically I'll update it to allow for both someone who's created a fork from the word go, as well as someone who cloned the mirror first.

Will share the proposed change here before I hit publish.

[psykro]

@tomd6r here is my suggested update, covering both options. Please let me know what you think.

Submitting a patch via GitHub

The WordPress core code has a [GitHub mirror](​https://github.com/wordpress/wordpress-develop) that allows you to create a patch via GitHub. This is useful for contributors who prefer using GitHub for code reviews and collaboration.

To contribute via GitHub, you’ll need to fork the WordPress GitHub mirror, clone it locally, create a branch for your changes, and push the branch to your fork.

1. Create a fork of the wordpress/wordpress-develop mirror under your own GitHub account, using the Fork option at the top of the GitHub page.
2. Clone your fork to your local computer. Use the SSH or HTTPS URL depending on your requirements. Replace your-username with your GitHub username.

git clone git@github.com:your-username/wordpress-develop.git

3. Create a new branch to work on a specific Trac ticket. Never work directly on trunk. A good practice is to name your branch after the Trac ticket number, and a brief description of the change. For example, if the ticket number is #44722, you might use 44722-fix-issue-in-component:

git checkout -b 44722-fix-issue-in-component

4. Make your code changes, commit them, and push your branch to your fork.

git push origin 44722-fix-issue-in-component

5. Go to your fork on GitHub. If your GitHub account is linked to your WordPress.org profile, GitHub will prompt you to open a Pull Request. Make sure the title includes the Trac ticket number (e.g., #44722: Fix X issue in Y component).

If you've already cloned the wordpress/wordpress-develop mirror locally, and you want to create a patch, you can add your fork to the local clone.

1. First, create the fork on GitHub, as detailed in step 1 above.
2. Then, add your fork as a remote repository in your local clone:

git remote add fork git@github.com:your-username/wordpress-develop.git

3. Fetch all remotes to make sure you have the latest updates:

git fetch --all

4. When creating the branch locally, make sure to specify the remote branch.

git checkout -b 44722-fix-issue-in-component fork/trunk

5. Alternatively, if you’re checking out an existing branch from your fork:

git checkout fork/44722-fix-issue-in-component fork

6. After making your changes, commit them and push to your fork:

git push fork 44722-fix-issue-in-component

For more details on GitHub integration, see the GitHub Pull Requests for Code Review documentation (​https://make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/).

[tomdevisser]

Looks great, @psykro! The only thing I’m a little hesitant about is whether it might be a bit too wordy, which could make it a bit harder to follow for some contributors.

I’d be totally fine with this being published as-is, but I’d like to offer one more suggestion:

---

Submitting a patch via GitHub

If you prefer using GitHub for code reviews and collaboration, the WordPress core code is available as a [GitHub mirror](​https://github.com/wordpress/wordpress-develop) where you can submit patches.

1. Fork the GitHub mirror to your own account using the Fork button on the GitHub page.
2. Clone your fork locally (replace your-username).

   git clone git@github.com:your-username/wordpress-develop.git
   

3. Create a new branch to work on a specific Trac ticket — never work directly on trunk. Name it after the Trac ticket number, and a brief description of the change.

   git checkout -b 44722-fix-issue-in-component
   

4. Make your changes, commit, and push.

   git push origin 44722-fix-issue-in-component
   

5. Go to your fork on GitHub. If your GitHub account is linked to your WordPress.org profile, GitHub will prompt you to open a Pull Request. Make sure the title includes the Trac ticket number (e.g., #44722: Fix X issue in Y component).

---

I left out the second part about adding your fork to an existing local clone. I initially kept it because it was in the original version, but I think more advanced users will already be familiar with that workflow. For newer contributors, it could be a bit disorienting or feel like an alternate path they have to consider. The examples (like naming the branch) are already covered implicitly in the example commands, so I figured simplifying it helps keep the focus clearer.

[psykro]

@tomd6r I agree with your suggestion, during my first pass at the rewrite I actually considered leaving out the remote forks bit entirely.

What about adding this short paragraph, just to cover that use case?

==

While first forking the mirror and then cloning it locally is recommended, if you've already cloned the wordpress/wordpress-develop mirror, you can add your fork as a remote repository using git remote add.

git remote add fork git@github.com:your-username/wordpress-develop.git

You'll then still be able to create a local branch, but will need to push to the correct remote.

To learn more about working with remote repositories, see the [GitHub documentation](​https://docs.github.com/en/get-started/git-basics/managing-remote-repositories).

[tomdevisser]

@psykro Perfect!

[psykro]

@tomdevisser the changes have been made, please review and let me know if we can close this ticket.

[tomdevisser]

Replying to psykro:

@tomdevisser the changes have been made, please review and let me know if we can close this ticket.

Looks great, thank you!

[psykro]

Thanks @tomdevisser