A detailed description of the workflows after we implemented phase 3

This is a summary and detailed implementation plan distilled of the orginal discussion over at http://groups.drupal.org/node/50438
While the orginal plan was written by CorniI, I expect this wiki page to be adjusted as we further clarify technical points. I also used content from the people contributing at the orginal wiki page.
This will then serve as a TODO list for the implementation of phase 3 of the migration to git.

In general, please fix any wording/grammar/whatever mistakes you find in here.
Please refrain from rehashing the discussion we already did. If you feel that you've to propose something you feel we missed, please check the old discussion first. We don't want to turn this wiki page in a 100 comment monster, really...
If you want to do substantial content changes to this document, please discuss them before applying.

In examples, Linda is the maintainer of a project P, while Alice, Bob and Peter are people contributing to a given issue I with the issue id #1.
All button names, etc. are just examples, these should be reviewed and adjusted by the UX team later.

Workflow A (WA):

Description:
Upload a patch to a d.o issue. We don't care how you created or developed that patch. This is pretty much what we use currently. We will fully support WA, but we'll offer you new (great ;)) ways of contributing.
Implementation:
- WA is already implemented. We only have to check that you can upload patches with git-like prefixes and without with the testbot still working.
There is work underway to further improve with WA using drush issue queue commands.

Workflow B (WB):

This new workflow is the one we emphasize on and which will hopefully used by the biggest part of the community not using WA. This workflow is fully integrated with git and thus inherently more complex than WA, but it also offers the developer much more possibilites, while still being partially compatible with WA.
This one needs lots of copy-paste advice spread all over the issue queue and the project pages, much like the current CVS instructions tab.
Description:
This workflow is centered around an issue-specific repository. Collaboration is done together in one branch. If there is disagreement on how an issue should be tackled, there's the possibility for multiple branches. Everyone who fulfills the access requirements (outlined below) has push access to this repository.
Detailed steps:

• Alice notices an issue within a project/wants to propose a new feature/whatever.
• Alice files I within P
• Alice decides that she'll work on I
• Alice clones the official repo of P with
  git clone -o P git://URL/P.git
• Alice hits the "Help on this issue" button on I
• As there was previously no repo for I, d.o creates and sets one up (see below for technical details of this). If there was already someone working on I with a repo, TODO!
• Alice gets a message with the content like this:
  "To work on this issue, cd into your clone of P and execute the following git commands:
  git checkout -b add-views-integration P/6.x-2.x-dev
  git remote add 1 git@drupal.org:git/issues/1.git
  "
  -NOTE: no tracking here, by intention
• Alice executes the given commands there
• Alice works and commits her work locally in the branch add-views-integration.
• This branch name is totally arbritary, but for doc issues we maybe want to standardize it. A simple issue no doesn't work here, because you've no idea on what you're working on if you see 1.
• When Alice decides to share her work, she does the following (which is somehwere to c&p on the issue page)
• TODO: do we want to enforce some branch naming conventions here to make things not too chaotic?
• git push 1 add-views-integration
• On d.o in the repo for I the branch add-views-integration is created. Access checks, repo restrictions, updating of the vcs_api db, etc are done in server-side repo hooks.
• Alice goes to the issue and posts a comment. She ticks a checkbox "Associate fix in repo with this comment" which allows her to select a branch name for the fix (in her case, only one selection, add-views-integration is possible).
• She enters a comment body describing her changes as usual.
• The comment now is a bit special: It contains a patch which is generated as following:
• In a temporary clone of P (we've to optimize this later, but for the example, you'll see how it works out) we checkout the branch I is against. Then we git pull /path/to/1.repo add-views-integration into it. This merges the branch in the current head. Then we save the output of git diff (maybe with --no-prefix) as patch file which is attached to the issue.
• We have to take care of merge conflicts, we will notice Alice somehow, maybe with a state like the testing bot, that add-views-integration don't merge into the current mainline.
• NOTE: This reduces the need to reroll greatly, because we employ git merge here, which is vastly superior to patch(1)
• NOTE2: We expect Alice to just merge from mainline, if there are merge conflicts. Everything else will add unnecessary merge commits we don't want.

• If there are any merge conflicts, Alice has to do the following:
  git pull origin (to get the latest commits for P)
  git checkout add-views-integration (if she's not on this branch currently)
  git merge origin/6.x-2.x-dev

  • resolve the merge conflicts
    git commit
    git push 1 add-views-integration

• We note on I which commit was in add-views-integration at the point of the posting of the comment. We need this to reroll the patch as P progresses. We need somehow a trigger when to reroll the patch. Maybe we want the testbot to trigger this, if it detects that the patch doesn't apply cleanly anymore (remember, the testbot re-tests every pending patch)

• When needed, d.o rerolls the patch. TODO: notification on rerolling in the issue??

• Alice now has successfully published her patch on d.o with git (these detailed steps git actually longer than i thought them to be...)

• Now, Bob, our reviewer steps in.

• Bob also hits a "Help with this issue" button and gets git commands like this:

  git remote add 1 git@drupal.org:git/issues/1.git -f -t add-views-integration
  Every branch in the per-issue repo is listed here as -t branch-name except the branches which are inherited from the per-project repo.
  To work on the issue now bob has to execute
  git checkout -b add-views-integration 1/add-views-integration -t
  -TODO: do we want the tracking here? I think we want, but i'm not sure.

• Bob now does some work and commits. To push he executes
  git push 1 add-views-integration
• repeat at the point where bob steps in

TODO: multiple branches in one per-issue repo!

Auto-setup of per-issue repositories - details:

we do a --bare clone of the per-project repo, with a local URL, using hardlinks.
we have to investigate the usage of git gc and git relink.

Access Requirements for repositories (except project-specific repositories):
We disallow pushing in the branches inherited from the per-project repo. Maybe we even want to delete them when creating the repo? This would save us the -t options on git remote add.
non-FF-pushes are disallowed. We probably don't want tags in the repo neither, i think, nor deleting of branches. Only Infra-team-ppl should be able to delete branches (for example if you pushed a branch belonging in issue 1 in the repo for issue 2...)

Initing a new project repository

This is a bit harder...
something along git clone empty-repo-on-d.o -o projectname
git symbolic-ref HEAD refs/heads/6.x-1.x for 6.x-1.x - depending on the drupal version
git add .
git commit -m "inital commit"
git push projectname 6.x-1.x
After the initial push d.o has to set the HEAD of the d.o repo to one of the pushed branches. In the usual case, we just get one branch in the first push.T

If we setup HEAD on the d.o repo it has no effect if the d.o repo is empty.

We need a way to set the active branch

When a user clones the repo of P, the branch specified in the repo on d.o in the HEAD file is checked out by default. There is no way in git to set HEAD to a specific branch over the
network. We need to provide a webinterface which allows setting HEAD to one of the project's development branches along with some explanations for what this setting is.

To update the whole work you're doing on a single project, execute git pull in the checkout. Maybe you need to resolve some merge conflicts in case your work in an issue branch is conflicting.

Workflow C

This allows you to create clones of P as a user-specific sandbox. You can do whatever you want in these user-specific sandboxes. You are not given any copy/paste commands besides cloning for these repos. It will not be supported by the ppl who help out in irc. If you want this kind of github-liek workflow, you can do it, but you've to know git enough by yourself. There will be no github-like network graph for example, because we already spend enough time implementing WB, and getting WC right requires a lot of time as well which we don't have.