Using a Sandbox project to collaborate

Last updated on
25 October 2021

This documentation needs review. See "Help improve this page" in the sidebar.

If you have a group that wants to collaborate on a software change, a workflow using patches and interdiffs on issues (as described in other pages in this section) does work very well. Instead, what you want is a repository that temporarily forks the project repository, where multiple people can commit changes.

Prior to July 2020, if you wanted to fork a project temporarily so that people could collaborate, you could either use an outside site like GitHub or you could create a "sandbox" project on drupal.org. Starting in July 2020, selected projects instead have the ability to fork the project temporarily on an issue; this will be coming to all projects soon.

Meanwhile, this page describes how to use a drupal.org sandbox project to collaborate.

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

Tags

Help improve this page

Page status: Needs review

You can: