Creating issue forks

Creating an issue fork

An issue fork is a temporary repository for working on source code changes for an issue. It starts out as a copy of the main repository for the project, but it allows all community members to commit and push changes. If you are on an issue page, and a fork has not yet been created for that issue, you can create an issue fork by clicking the Create issue fork button below the issue summary on the issue page:

Understanding the issue fork area

After one or more branches and merge requests have been made on an issue fork, the Issue fork area below the issue summary on the issue page may look rather complex:

Here is a list of what this area may contain, from top to bottom:

• A link to the GitLab page for the issue fork. The link text is the fork repository name, which is PROJECT-ISSUE_NUMBER where PROJECT is the short/machine name of the project, and ISSUE_NUMBER is the issue number (example: drupal-3181657).
• Either a button where you can Get push access, or text saying You have push access.
• A link saying Show commands, which will show you commands to clone the issue fork and other useful operations.
• One or more branch and merge request sections (one per branch that has been created). Each section contains (some areas will not be present if a merge request has not yet been created on this branch):
  • A link to the branch on GitLab, whose text is the branch name (example: 3181657-test-only).
  • Next to the branch link, the compare link, which links to a Compare page on GitLab. This lets you compare the code in the branch to the base version. If a merge request has been opened for the branch, compare is replaced with changes, which links to the merge request’s changes.
  • A link to download the plain diff (a patch file)
  • A link to a merge request, if there is one yet (link text will be something like "MR !24 mergeable").
  • The latest test results summaries from the automated tests for the merge request (if there is one), which link to the test results page, and links to add additional tests or retest.
  • A link to view a live preview of a site with this merge request applied. Live previews are available for any merge request against Drupal core. Live previews are also available to contrib modules that opt in. See the Using live previews on Drupal Core and contrib merge requests page for more information about using live previews.
• A link to create a New branch, if there aren't any yet.
• A link to the About issue forks page.

Cloning and committing code to an issue fork

Making changes remotely in a browser (simple)

If you're not very familiar with git commands, but just want to easily submit some changes to an issue, you can do this directly in a web browser, without any additional tools:

1. Click on the Issue fork link to open the GitLab interface.
2. Navigate to the file you wish to change and click its filename to open it.
3. Click on the blue Edit drop-down menu, then on Open in Web IDE. The file will open in the GitLab Web IDE in a new browser tab or window.
4. Make your changes. You can copy-paste code from your local file.
5. Save your changes ("Hamburger" menu at the top left > File > Save (or CTRL+S, CMD+S etc.)).
6. When you have finished making your changes on all files, click the "Source Control" icon at the left, which should show the number of pending changes.
7. Click the Commit to 'branch_name' button, to commit and push your changes.

Making changes locally (requires some Git commands)

Follow these steps to work on code on your local machine and commit it to a fork that has been created for an issue:

.

1. Consider assigning the issue to yourself in the Assigned menu in the issue metadata, to let other developers know you're working on it.
2. Get set up for Git, including setting up Git authentication.
3. Follow the steps on Cloning a Drupal Git repository to clone the development branch of the project matching the version for the issue to your computer.
4. Run a git pull command to make sure you have the latest code on the development branch you are working on.
5. Back on the issue page, click the Get push access button in the issue fork area. The button should change to text saying You have push access.
6. Click the Show commands link in the issue fork area. Copy and run the commands under Add & fetch this issue fork’s repository.
7. • If you wish to work on an existing branch on the fork, copy and run the command under Check out this branch under the Show commands link in the issue fork area.
   • Alternatively, if you are the first person to code on the fork, create a new branch in the fork to work on changes. Use a command like git checkout -b NEW_BRANCH_NAME. A good branch name would be the issue number followed by a short description. e.g. 3982435-ckeditor-5-compatibility.
8. It's a good idea to run git branch --show-current to verify you are working on the branch you intend to.
9. Make your changes to the code locally.
10. Run git status at any time to check the status, and git diff to see the changes you have made. You may need to press Q to return to your terminal prompt.
11. Stage your changes locally, ready for committing. To stage all changes, you might use git add -A.
12. It's a good idea to run a final git status to verify which modified files are ready to be committed.
13. Commit your changes locally. To commit all changes with a message summarizing the changes you are making, you might use git commit -a -m DESCRIPTIVE_NOTE. Don't forget the quotation marks around your message! e.g. git commit -a -m "Remove deprecated code".
14. When you are sure you are ready, push your changes to the fork. Note that Git commits are permanent after a push, so be sure!
    • If you are working on an existing branch on the fork, just run git push.
    • Alternatively, if you are the first person coding on the fork, run git push FORK_NAME NEW_BRANCH_NAME. e.g. git push my_module-3982435 3982435-ckeditor-5-compatibility.

    If asked, enter your ssh key passphrase.

15. A notice will be added to the issue comments section for each pushed commit.
16. Unlike comments, commit notices no longer generate email messages to issue followers. So add a new comment to the issue, explaining the commits you have made and pushed.  You can of course be more verbose in a comment than in the commit message.
17. Consider uploading a patch file to the issue in addition to making a merge request, especially if your changes solve a problem. Although the recommended way to contribute source code changes is via merge requests, patches can be easier for others to install via Composer. Patches can be downloaded from merge requests, or created locally via Git.

Pulling in new branches from an issue fork's parent

In some cases (like a long-running core issue) you may find yourself wanting to create a new issue-branch against the latest development fork. However, issue forks are just git repositories like any other. If they were created before the branch was created on the parent repository, that branch will not exist in the fork.

To pull in a branch from the parent and push it to your issue fork: 

1. Make sure your local copy was set up properly with two remotes. If you followed the instructions from the issue page, or in the Cloning and committing code to an issue fork section above, you should already have the parent repository available as a remote, in addition to the issue fork. 
   • 1 remote should be the true origin repository for the project. Use git remote | grep origin to see if you have the origin remote.
   • 1 remote should be the issue fork remote. Use git remote | grep [your issue number] to see if you have the issue fork remote.
2. You can then pull the latest branches from the parent origin, and push them to the issue-fork origin. For instance, to add Drupal Core 10.1.x, you could do this: git checkout 10.1.x && git pull origin 10.1.x && git push [your issue fork remote] 10.1.x.
3. From there, if you use the 'create new branch' button under the issue summary, you should be able to select the new branches as the basis for your issue branch.