[TYPO3-doc] Encouraging people to contribute with Github

[Xavier Perseguers]

Hi all,

During the developer days, we sat together with Francois and I tested
and documented how to contribute with Github while keeping the process
with Gerrit.

I'd like to share this in this ML to be further discussed. Steffen
Gebert told me (via Twitter) that a plugin exists for Gerrit which would
allow people to easily contribute, I really don't know how the workflow
would look like.

The general workflow for contributing via Github would be to have a
synchronized fork of each manual on Github. People would then
fork/contribute via pull request on Github, the requests would be merged
on Github, sync back as patches locally which would be sent to Gerrit
for the standard review and merged.

Feel free to comment on that.

Cheers
Xavier


My notes about the whole process:

1. Fork project on Github

     1. Bare clone a repository

          $ git clone --bare
git://git.typo3.org/TYPO3CMS/Extensions/sphinx.git

     2. Create an empty project on Github

     3. Push the bare clone to Github

          $ cd /path/to/sphinx.git
          $ git push --mirror git at github.com:xperseguers/sphinx-test.git

2. Work on Github (pull requests, commits, …)

3. Retrieve changes from Github and push to Gerrit

     1. Go to working clone of the extension
     2. Add an additional origin

          $ git remote add github git at github.com:xperseguers/sphinx-test.git

     3. Fetch changes from github

          $ cd /path/to/sphinx (standard working clone)
          $ git pull github master

     4. Possibly amend/whatever

     5. Push to Gerrit

          $ git push origin HEAD:refs/for/master

     6. After merge, resync local + Github

          $ git pull
          $ git pull github master
          $ git pull

          --- local repo should be clean ---

     7. Resync Github with non-fast-forward :)

          $ git push github +master


=====================
A few use cases
=====================


Squash multiple commits on Github
=================================

1. Github has 2 new commits f22ac3888843f79ccb8dde145d0bd6314ef1c8ca and
360c4fc59234cf93ea4a2da732850b7cdee9aba0

2. git pull github master

$ git status
# On branch master
# Your branch is ahead of 'origin/master' by 2 commits.
#   (use "git push" to publish your local commits)
#
nothing to commit, working directory clean

$ git rebase -i

pick f22ac38 Adding missing blank lines between sections
pick 360c4fc Update Index.rst

# Rebase 38608dc..360c4fc onto 38608dc

=> CHANGE THAT TO

pick f22ac38 Adding missing blank lines between sections
squash 360c4fc Update Index.rst

=> THEN EDIT COMMIG MESSAGE which leads to

[detached HEAD 3150953] [TASK] Add missing blank lines between sections
 Author: Xavier Perseguers <typo3 at perseguers.ch>
 2 files changed, 4 insertions(+), 1 deletion(-)
Successfully rebased and updated refs/heads/master.

$ git status

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#   (use "git push" to publish your local commits)
#
nothing to commit, working directory clean

push to Gerrit and review:

$ git push origin HEAD:refs/for/master

Then as usual:

$ git pull
$ git pull github master

$ git status
# On branch master
# Your branch and 'origin/master' have diverged,
# and have 2 and 1 different commit each, respectively.
#   (use "git pull" to merge the remote branch into yours)
#
nothing to commit, working directory clean

$ git pull
First, rewinding head to replay your work on top of it...
Applying: Adding missing blank lines between sections
Using index info to reconstruct a base tree...
M     Documentation/Administration/InstallingExtension/Index.rst
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.
Applying: Update Index.rst
Using index info to reconstruct a base tree...
M     Documentation/Administration/WindowsSetup/Index.rst
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.

$ git status
# On branch master
nothing to commit, working directory clean

Push back to Github:

$ git push github +master
Counting objects: 15, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (8/8), 781 bytes | 0 bytes/s, done.
Total 8 (delta 5), reused 0 (delta 0)
To git at github.com:xperseguers/sphinx-test.git
 + 360c4fc...313f3db master -> master (forced update)

=> History on Github has been rewritten!


-- 
Xavier Perseguers
Release Manager TYPO3 4.6

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org