Using a Sandbox project to collaborate

Since July 2020, it has been possible to fork Drupal projects on Gitlab. That workflow is integrated with Drupal issues and is now the preferred method for collaboration.

It is also possible to collaborate by using patches and interdiffs on issues (as described in other pages in this section). That workflow has been used effectively in the past but is now discouraged.

This page describes a third option for collaboration: How to temporarily fork a project repository as a drupal.org sandbox project, where multiple people can commit changes.

Setting up a sandbox for collaboration

1. Create a new sandbox project on drupal.org by visiting drupal.org/project/add and clicking the link for the type of project. Be sure to choose Sandbox instead of Full project.
2. Edit the sandbox project and add your collaborators as maintainers who can maintain issues and commit to the Git repository for the sandbox.
3. Clone the repository you want to fork.
4. In the cloned repository, create a new branch (git checkout -b NEW_BRANCH_NAME), and optionally delete the existing branches (git branch -d OLD_BRANCH_NAME).
5. Rename the remote for the cloned repository (you'll need it for merging in changes):
   git remote rename origin REPONAME_official
6. Visit the "Version control" tab for the sandbox project and find the clone URL. Set the "origin" remote for the cloned repo to this URL, and push the code to it:
   

   git remote add origin CLONE_URL
   git push origin NEW_BRANCH_NAME
   

7. If we're using git 7.0+, we can turn our branch into a tracking branch:
   

   git branch --set-upstream cool_new_public_branch origin/cool_new_public_branch
   

At this point, your collaborators can visit the "Version control" tab for the sandbox project, follow the instructions there to clone the project, and commit code. You'll also have an issue workspace to use for individual tasks, feature requests, and bugs for the sandbox.

Merging in changes

Whenever you think changes in the upstream module are significant, you can merge the changes from the source repository into your branch

git fetch REPONAME_official
git merge REPONAME_official/OLD_BRANCH_NAME
git push origin NEW_BRANCH_NAME

Making a patch

When you are ready to make a patch for submission on an issue in the original repository:

git diff REPONAME_official > PATCHFILE.patch