Collaborating with the drupal.org Git sandbox

Last updated June 7, 2011.

Sandboxes can be used for many things, and one of the things they will be used for is for teams collaborating on larger projects, or adding large features to core or existing modules, etc. This is a poor-man's solution to the lack of per-issue repositories, which will be coming in Git phase 3.

In that situation we have a couple of new complexities:

• We (possibly) have multiple collaborators who can commit.
• If this is a feature of an existing project we will occasionally have to sync it up with that project so we don't have a massive soul-crushing merge when the time comes to do so.

This is one possible workflow for this situation:

1. Create a new sandbox on drupal.org. Mine will be named my_views_feature, and it will be a new feature for the views project. The committer URL will be
   
   rfay@git.drupal.org:sandbox/rfay/1056659.git
2. Clone the views repository into a directory named my_views_feature:
   
   git clone --branch 7.x-3.x git://git.drupal.org/project/views my_views_feature
cd my_views_feature
3. Create a branch that we'll use as a public branch (one that will be pushed to the Drupal.org repository and can be cloned and contributed to by others).
   
   git checkout -b cool_new_public_branch
4. Delete the 7.x-3.x branch, as we could just get confused by it.
   
   git branch -d 7.x-3.x
5. We're not going to be working off of the official views repository, but we still need it for syncing up, so we'll rename it.
   
   git remote rename origin views_official
6. Now set the "origin" remote to our sandbox and push our code to it:
   
   git remote add origin rfay@git.drupal.org:sandbox/rfay/1056659.git
git push origin cool_new_public_branch
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
8. Now people can clone this:
   
   # Committers:
git clone --branch cool_new_public_branch somebody@git.drupal.org:sandbox/rfay/1056659.git
# Non-committers using patch workflow:
git clone --branch cool_new_public_branch http://git.drupal.org/sandbox/rfay/1056659.git
9. Now work goes on. The team can use a rebase workflow or a patch workflow or an integration manager workflow. But somehow the branch named cool_new_public_branch has new commits on it.
10. Avoid merging in the ongoing work in the Views 7.x-3.x branch unless you know there's a significant collision or a feature you need or something like that. But when you need work that's going on there, merge it in with this code. Note that we cannot rebase here because this is a publicly exposed branch and we'd be rewriting the history (and not just doing fast-forward commits).
    
    # Make sure we have the latest
git pull
# Fetch the current views work from the views repo
git fetch views_official
# Merge the views work into ours
git merge views_official/7.x-3.x
# Push the changes up to cool_new_public_branch
git push origin cool_new_public_branch
11. When the time comes to create a patch for submission to the views queue, create a patch:
    
    git fetch views_official
git diff views_official >/tmp/views.cool_new_feature.patch

Here is the stuff that was here before

In addition to the typical patch contributor workflow, sometimes you want to tackle a major inititiave, such as a core initiative to add native HTML5 support to Drupal's markup, create a brand new database abstraction layer, or similar chunk of work that will take many weeks or months, affect many areas of the code, and often require coordination of a team of multiple people. In such a situation, this is the best approach.

Prerequisite: Every workflow requires the initial set up detailed in Using Git on Drupal.org.

// TODO:
- We should resolve http://drupal.org/node/1057228 one way or another; right now it's not clear what to choose when you create a sandbox project.
- It'd be nice to have documentation to point off to about how to add maintainers to projects.

1. The initiative leader creates an issue in the issue queue to centrally track the effort. This issue should be updated periodically with the ongoing status of the initiative, as well as patches that reviewers can review and testbot can validate.
2. The initiative leader also creates a sandbox project and assigns any collaborators as co-maintainers to the project.
3. The sandbox is now initialized in this way:
   
   # clone the project (one time operation)
git clone --branch [version] http://git.drupal.org/project/[name].git

# branch for the initiative (one time operation)
cd drupal
git checkout -b [initiative-shortname] master

# work: git add, git commit, etc.

# add the sandbox push url as remote (one time operation)
git remote add sandbox [git-username]@git.drupal.org:sandbox/[leader-git-username]/[sandbox-number].git

# push the code worked to the sandbox
git push sandbox [initiative-shortname]
# Note this can take a long time since it's parsing 20,000 commits
4. Other co-maintainers can clone and push to the sandbox as well:
   
   # clone with push url
git clone [git-username]@git.drupal.org:sandbox/[leader-git-username]/[sandbox-number].git

# work: git add, git commit, etc

# push the code worked to the sandbox (since we cloned we add a
# default remote called origin that is used on push by default)
git push
5. Other non-co-maintainers can also contribute to the project as defined on Patch contributor guide.
6. Once your team hits a good stopping point, then you should upload a patch to the issue to allow folks tracking that issue to respond, and to give testbot a crack at it.
   
   # go to your topic branch
git checkout [initiative-shortname]

# generate a patch against current code
git diff master > [initiative-shortname].patch