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:

When creating the issue fork, you have the option to create a new branch from the default branch at the same time. In general, that is a good practice, especially for making significant changes, or collaborating between multiple contributors.

The default new branch name consists of the issue number followed by a description generated from the issue title. If the description does not make sense (e.g. It has been truncated), you can alter or extend it. Git's character limit is 255, but keep it concise for readability, and separate words by hyphens.

For simple changes by a single developer, working directly on the default issue fork branch may be easier and more efficient, so the box can be unchecked in that case.

Understanding the issue fork area

If an issue fork has been created, the Issue fork area below the issue summary on the issue page may contain various elements. The exact content depends on the state of the fork, such as whether branches or merge requests have been created:

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, formatted as PROJECT-ISSUE_NUMBER, where PROJECT is the short/machine name of the project, and ISSUE_NUMBER is the issue number (e.g. drupal-3181657).
• Either a button labeled Get push access, or text stating You have push access.
• A link labeled Show commands, which displays commands to:
  • Add & fetch the issue fork's repository with authentication via SSH keys.
  • Add & fetch the issue fork's repository with authentication over HTTPS.
  • Check out branches.
  • Push your current local branch from your Git clone (if you have push access).
• Sections for branches and merge requests (if any have been created). Each section may include the following:
  • A link to the branch on GitLab, with the branch name as the link text (e.g. 3181657-test-only).
  • Next to the branch link, a compare link that opens a page on GitLab that allows you to compare the branch code to the base version. If a merge request exists, compare is replaced with changes, linking to the merge request's Changes page.
  • A link to download the branch's plain diff (a patch file).
  • A link to the merge request, if one exists (e.g., "MR !24 mergeable").
  • The latest test result summaries for the merge request, linking to the test results page, along with links to trigger additional tests or retests.
  • A link to view a live preview of a site with the merge request applied. Live previews are available for any merge request against Drupal core and for contrib modules that opt in. For more details, see Using live previews on Drupal Core and contrib merge requests.

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 branch name you wish to contribute to, to open it its repository in the GitLab interface. If no branches exist and/or you wish to contribute directly on the issue fork, click on the Issue fork link instead. You can switch between branches using the dropdown menu on GitLab.
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.
8. When you have finished committing your changes, and you think the code is ready for review and testing, you can create a merge request.

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. When you have finished committing your changes, and you think the code is ready for review and testing, you can create a merge request.
18. 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.