Skip to end of metadata
Go to start of metadata

<h2>Initial Setup</h2>

<p>First, make sure you know the email address associated with your JIRA credentials. All commits pushed to the master repository are checked against these addresses, so your repository will need to be configured to use that address. The following will give you that information:</p>

<ul>
<li>Visit the ZF Crowd install: <a class="external-link" href="http://framework.zend.com/crowd">http://framework.zend.com/crowd</a></li>
<li>Log in, if you aren't.</li>
<li>Find the "My Profile" link in the upper right of the page, and follow it.</li>
<li>The resulting page will display your profile, including the <em>email</em> address with which you are registered. Make a note of it.</li>
</ul>

<ac:macro ac:name="note"><ac:parameter ac:name="title">Windows Users</ac:parameter><ac:rich-text-body>
<p>If you use Windows, and are unfamiliar with using Git or using Git on Windows, we recommend reading <a href="http://help.github.com/win-set-up-git/">the illustrated guide to git on windows</a>.</p></ac:rich-text-body></ac:macro>

<h3>Setup your own public repository</h3>

<p>Your next step is to establish a public repository from which we can pull your work into the master repository. You have two options: use github or other public site, or setup/use your own repository.</p>

<h4>Option 1: GitHub</h4>

<ul>
<li>Setup a <a href="http://github.com/">GitHub</a> account, if you haven't yet</li>
<li>Fork the <a href="http://github.com/zendframework/zf2">ZF2 repository</a></li>
<li>Setup an ssh key for github to use (if you haven't yet), using this explanation: <a class="external-link" href="http://help.github.com/linux-key-setup/">http://help.github.com/linux-key-setup/</a></li>
<li>Clone your fork locally and enter it (use your own GitHub username in the statement below)
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git clone git@github.com:<username>/zf2.git
% cd zf2
]]></ac:plain-text-body></ac:macro></li>
<li>Configure git to use the email address with which you are registered in JIRA:
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git config user.email <your email address>
]]></ac:plain-text-body></ac:macro></li>
<li>Add a remote to the canonical ZF repository (or GitHub mirror), so you can keep your fork up-to-date:
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git remote add zf2 git://github.com/zendframework/zf2.git

  • AND -
    % git fetch zf2
    ]]></ac:plain-text-body></ac:macro></li>
    </ul>

<h4>Option 2: Personal Repository</h4>

<p>We assume you will use <a href="http://scie.nti.st/2007/11/14/hosting-git-repositories-the-easy-and-secure-way">gitosis</a> or <a href="http://progit.org/book/ch4-8.html">gitolite</a> 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.</p>

<ul>
<li>Create a new repository
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git init
]]></ac:plain-text-body></ac:macro></li>
<li>Configure git to use the email address with which you are registered in JIRA:
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git config user.email <your email address>
]]></ac:plain-text-body></ac:macro></li>
<li>Add an "origin" remote pointing to your gitosis/gitolite repo:
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git remote add origin git://yourdomain/yourrepo.git
]]></ac:plain-text-body></ac:macro></li>
<li>Add a remote for the ZF repository and fetch it
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git remote add zf2 git://git.zendframework.com/zf.git
% git fetch zf2
]]></ac:plain-text-body></ac:macro></li>
<li>Create a new branch for the ZF repository (named "zf/master" here)
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git branch -b zf/master zf2/master
]]></ac:plain-text-body></ac:macro></li>
<li>Create your master branch off the ZF branch, and push to your repository
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git branch -b master
% git push origin HEAD:master
]]></ac:plain-text-body></ac:macro></li>
</ul>

<h2>Keeping Up-to-Date</h2>

<p>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:</p>

<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git checkout master
% git pull zf2 master

  • OPTIONALLY, to keep your remote up-to-date -
    % git push origin
    ]]></ac:plain-text-body></ac:macro>

<h2>Working on Zend Framework</h2>

<p>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.</p>

<p>A typical work flow will then consist of the following:</p>

<ul>
<li>Create a new local branch based off your master branch.</li>
<li>Switch to your new local branch. (This step can be combined with the previous step with the use of `git checkout -b`.)</li>
<li>Do some work, commit, repeat as necessary.</li>
<li>Push the local branch to your remote repository.</li>
<li>Send a pull request.</li>
</ul>

<p>We recommend naming your branches as follows:</p>

<ul>
<li>"hotfix/<issue ID>" for bugfixes; e.g. "hotfix/ZF-9295"</li>
<li>"feature/<feature name>" for features; e.g., "feature/translate-resource-es"</li>
</ul>

<p>The mechanics of this process are actually quite trivial. Below, we will create a branch for fixing an issue in the tracker.</p>
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% 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
]]></ac:plain-text-body></ac:macro>

<p>To send a pull request, you have two options.</p>

<p>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.</p>

<p>If using your own repository - or even if using GitHub - you can send an email indicating you have changes to pull:</p>

<ul>
<li>Send to <a class="external-link" href="mailto:zf-devteam@zend.com">zf-devteam@zend.com</a></li>
<li>In your message, specify:
<ul>
<li>The URL to your repository (e.g., "git://mwop.net/zf2.git")</li>
<li>The branch containing the changes you want pulled (e.g., "hotfix/ZF-9295")</li>
<li>The nature of the changes (e.g., "implements Zend_Service_Twitter", "fixes ZF-9295", etc.)</li>
</ul>
</li>
</ul>

<p>In order to generate the pull request message automatically <a href="http://www.kernel.org/pub/software/scm/git/docs/git-request-pull.html">git-request-pull</a> may be used. </p>

<p>For example, to ask to pull changes from <strong>milestones/exceptions/slideshare</strong> branch on your github fork <strong>git@github.com:USERNAME/zf2.git</strong> into <strong>zf2/milestones/exceptions</strong>:</p>

<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git request-pull zf2/milestones/exceptions git@github.com:USERNAME/zf2.git milestones/exceptions/slideshare
]]></ac:plain-text-body></ac:macro>

<p>The above will generate message you can send to <a class="external-link" href="mailto:zf-devteam@zend.com">zf-devteam@zend.com</a>, it has all necessary bits of information injected.</p>

<h2>Branch Cleanup</h2>

<p>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.</p>

<p>Once you know that your changes have been accepted to the master repository, we suggest doing some cleanup of these branches.</p>

<ul>
<li>Local branch cleanup
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git branch -d <branchname>
]]></ac:plain-text-body></ac:macro></li>
<li>Remote branch removal
<ac:macro ac:name="code"><ac:default-parameter>sh</ac:default-parameter><ac:plain-text-body><![CDATA[
% git push origin :<branchname>
]]></ac:plain-text-body></ac:macro></li>
</ul>

<h2>Feeds and Emails</h2>

<p>RSS feeds may be found at:</p>

<ul>
<li><a class="external-link" href="https://github.com/zendframework/zf2/commits/">https://github.com/zendframework/zf2/commits/</a><branch>.atom</li>
</ul>

<p>where <branch> is a branch in the repository.</p>

<p>To subscribe to git email notifications, send an email to:</p>

<ul>
<li><a class="external-link" href="mailto:zf-git-subscribe@lists.zend.com">zf-git-subscribe@lists.zend.com</a></li>
</ul>

<p>You will need to reply to the verification email sent to you by this list.</p>

<p>Should you wish to filter emails from the list, they will use the "subject" line of commit messages, preceded by "<ac:link><ri:page ri:content-title="branch" /></ac:link> ", and come from "zf-git@lists.zend.com".</p>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jun 18, 2010

    <p>I recommend to name the ZF2 repository remote 'upstream' instead of 'zf2'. This is so you can keep it consistent if you are also contributing to other projects using git.</p>

    <p>Another recommendation is for the github users, to use git://git.zendframework.com/zf.git as the remote. This since the zf2 mirror on github isn't updated as fast as updates come in on the official repository.</p>

    <p>Oh, and for the github pull requests, who should we send the pull request to ?</p>

    1. Jun 18, 2010

      <p>github pull requests go to zf-devteam already. <ac:emoticon ac:name="smile" /></p>

      1. Jun 18, 2010

        <p>Well, if you make a github pull request the way you suggest, you get this screen:</p>

        <p><a class="external-link" href="http://images.firal.org/caps/9516c0.png">http://images.firal.org/caps/9516c0.png</a></p>

        <p>What my question is: what username should I select? I guess this is the 'zendframework' github user, but it might be a good idea to be a little more clear about this <ac:emoticon ac:name="wink" />.</p>

        1. Jun 18, 2010

          <p>Ah – yes – that's exactly the user. I'll update the doc.</p>

    2. Jun 18, 2010

      <p>I understand your reasoning for naming it "upstream". However, on my own repository, I'm attaching to both git and svn – which makes "upstream" nebulous. I went for a more explicit name in the case of these examples for this reason.</p>

  2. Jul 10, 2010

    <p>@Matthew and @Pieter kokx: sometime i am happy with your text. sometimes i became angry with your descriptions. For ZF 2.0 i am completely angry, many migrations will need, many changes is made, dont know documentation will again be sucked!, its a f... nightmare framework (FNF).</p>

    <p>its very good, you rule ZF. But its very evil and bad, you dont wirte transparent (you dont care head and tail), for rest of the world? The words are not belongs to you and only to your team, its in public, world is reading your word's, they have individual teams/teams leaders.</p>

    <p>Please be specific for ZF 2.0!:<br />
    1. Qt how to git?<br />
    2. JDeveloper how to git?<br />
    2. Netbeans how to git?<br />
    3. Eclipse how to git?</p>

    <p>Try to make things kiss ("keep it simple stupid's"). </p>

    <p>Thanks in advance</p>

    1. Jul 11, 2010

      <p>Well shams, change is <strong>needed</strong>. If you don't innovate, you will be stuck in the past. And I will assure you, if we wouldn't change ZF so 'drastically' with version 2.0, we will be hailed by all other frameworks around in under two years.</p>

      <p>This is just a very simple guide, and I agree with you that it isn't finished. Also, this is a space clearly for ZF contributors, not for 'the world'. And most ZF contributors already know a bit about git, and they know how to use google.</p>

      <p>Writing guides for every way to use git in IDE's, simply isn't feasible at all. I know that both me and Matthew don't use IDE's (we're both vim users), so we cannot exactly describe how this all should work in <name-your-IDE>. And another thing is that if its hard with an IDE to translate git commands to how the IDE works with git, I'm quite sure that the IDE's git support is very poor.</p>

      <p>Also note that besides ZF, most of us have a life too.</p>

      <p>Oh, and you can edit the page too you know <ac:emoticon ac:name="wink" />.</p>

    2. Mar 04, 2011

      <p>shams: I missed this comment come through, evidently, so my apologies for the late reply.</p>

      <p>I really don't understand your anger at all. I don't understand what you mean by "you dont wirte transparent (you dont care head and tail), for rest of the world" – this wiki is public, and anybody who has an account can edit it and add pages to it.</p>

      <p>I can't tell you how to use Git on Qt, JDeveloper, Netbeans or Eclipse. However, if <strong>you</strong> can, or another contributor can, you're free to write up a page detailing the process. It makes more sense for developers who <strong>use</strong> those tools to write these pages, to ensure that the correct information is provided.</p>

      <p>Finally, yes, we're aware people will need a migration path. We will be providing an SVN mirror of the Git repo, likely around the time we go beta, so that developers using svn can continue to use svn:externals. Additionally, we'll be writing guides for how to utilize ZF2 as either a git submodule or via git subtree merging. For now, however, those efforts don't make sense as the repository is highly volatile.</p>

  3. Aug 03, 2010

    <blockquote><p>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.</p></blockquote>

    <p>When doing a pull request there is no such user as 'zendframework'. I can though open <a class="external-link" href="http://github.com/zendframework">http://github.com/zendframework</a> which is an organization. Is this a github bug and one should just type 'zendframework' manually?</p>

  4. Dec 09, 2010

    <p>Hello there,</p>

    <p>I thought I should add this step which is needed before you clone the fork locally (option 1).</p>

    <p><a href="http://help.github.com/linux-key-setup/">http://help.github.com/linux-key-setup/</a><br />
    (this is for linux... I'm not that adventurous to be using windows for development!)</p>

    <p>You might want to edit this guide to include this step in order to save some poor souls from frustration...</p>

    <p>Cheers,<br />
    Angel</p>

    1. Mar 05, 2012

      <p>Thanks a million, I am one of the poor souls you saved! And I edited the guide, to give this great tip a more prominent place.</p>