% git clone git@github.com:<username>/zf2.git
% cd zf2
{code}
* Configure git to use the email address with which you are registered in JIRA:
{code:sh}
% git config user.email <your email address>
{code}
* Add a remote to the canonical ZF repository (or GitHub mirror), so you can keep your fork up-to-date:
{code:sh}
% git remote add zf2 git://github.com/zendframework/zf2.git
- OR -
% git remote add zf2 git://git.zendframework.com/zf.git
- AND -
% git fetch zf2
{code}
h4. Option 2: Personal Repository
We assume you will use [gitosis|http://scie.nti.st/2007/11/14/hosting-git-repositories-the-easy-and-secure-way] or [gitolite|http://progit.org/book/ch4-8.html] to host your own repository. If you go this route, we will assume you have the knowledge to do so, or know where to obtain it. We will not assist you in setting up such a repository.
* Create a new repository
{code:sh}
% git init
{code}
* Configure git to use the email address with which you are registered in JIRA:
{code:sh}
% git config user.email <your email address>
{code}
* Add an "origin" remote pointing to your gitosis/gitolite repo:
{code:sh}
% git remote add origin git://yourdomain/yourrepo.git
{code}
* Add a remote for the ZF repository and fetch it
{code:sh}
% git remote add zf2 git://git.zendframework.com/zf.git
% git fetch zf2
{code}
* Create a new branch for the ZF repository (named "zf/master" here)
{code:sh}
% git branch -b zf/master zf2/master
{code}
* Create your master branch off the ZF branch, and push to your repository
{code:sh}
% git branch -b master
% git push origin HEAD:master
{code}
h2. Keeping Up-to-Date
Periodically, you should update your fork or personal repository to match the canonical ZF repository. In each of the above setups, we have added a remote to the Zend Framework repository, which allows you to do the following:
{code:sh}
% git checkout master
% git pull zf2 master
- OPTIONALLY, to keep your remote up-to-date -
% git push origin
{code}
h2. Working on Zend Framework
When working on Zend Framework, we recommend you do each new feature or bugfix in a new branch. This simplifies the task of code review as well as of merging your changes into the canonical repository.
A typical work flow will then consist of the following:
* Create a new local branch based off your master branch.
* Switch to your new local branch. (This step can be combined with the previous step with the use of `git checkout -b`.)
* Do some work, commit, repeat as necessary.
* Push the local branch to your remote repository.
* Send a pull request.
We recommend naming your branches as follows:
* "hotfix/<issue ID>" for bugfixes; e.g. "hotfix/ZF-9295"
* "feature/<feature name>" for features; e.g., "feature/translate-resource-es"
The mechanics of this process are actually quite trivial. Below, we will create a branch for fixing an issue in the tracker.
{code:sh}
% git checkout -b hotfix/ZF-9295
Switched to a new branch 'hotfix/ZF-9295'
... do some work ...
% git commit
... write your log message ...
% git push origin hotfix/ZF-9295:hotfix/ZF-9295
Counting objects: 38, done.
Delta compression using up to 2 threads.
Compression objects: 100% (18/18), done.
Writing objects: 100% (20/20), 8.19KiB, done.
Total 20 (delta 12), reused 0 (delta 0)
To ssh://git@github.com/weierophinney/zf2.git
b5583aa..4f51698 HEAD -> master
{code}
To send a pull request, you have two options.
If using GitHub, you can do the pull request from there. Navigate to your repository, select the branch you just created, and then select the "Pull Request" button in the upper right. Select the user "zendframework" as the recipient.
If using your own repository - or even if using GitHub - you can send an email indicating you have changes to pull:
* Send to mailto:zf-devteam@zend.com
* In your message, specify:
** The URL to your repository (e.g., "git://mwop.net/zf2.git")
** The branch containing the changes you want pulled (e.g., "hotfix/ZF-9295")
** The nature of the changes (e.g., "implements Zend_Service_Twitter", "fixes ZF-9295", etc.)
In order to generate the pull request message automatically [git-request-pull|http://www.kernel.org/pub/software/scm/git/docs/git-request-pull.html] may be used.
For example, to ask to pull changes from *milestones/exceptions/slideshare* branch on your github fork *git@github.com:USERNAME/zf2.git* into *zf2/milestones/exceptions*:
{code:sh}
% git request-pull zf2/milestones/exceptions git@github.com:USERNAME/zf2.git milestones/exceptions/slideshare
{code}
The above will generate message you can send to mailto:zf-devteam@zend.com, it has all necessary bits of information injected.
h2. Branch Cleanup
As you might imagine, if you are a frequent contributor, you'll start to get a ton of branches both locally and on your remote.
Once you know that your changes have been accepted to the master repository, we suggest doing some cleanup of these branches.
* Local branch cleanup
{code:sh}
% git branch -d <branchname>
{code}
* Remote branch removal
{code:sh}
% git push origin :<branchname>
{code}
h2. Feeds and Emails
RSS feeds may be found at:
* http://git.zendframework.com/feeds/<branch>.xml
where <branch> is a branch in the repository.
To subscribe to git email notifications, send an email to:
* mailto:zf-git-subscribe@lists.zend.com
You will need to reply to the verification email sent to you by this list.
Should you wish to filter emails from the list, they will use the "subject" line of commit messages, preceded by "[branch] ", and come from "zf-git@lists.zend.com".
...