|
| 1 | +# USING THE GIT REPOSITORY |
| 2 | + |
| 3 | +## Setup your own public repository |
| 4 | + |
| 5 | +Your first step is to establish a public repository from which we can |
| 6 | +pull your work into the master repository. You have two options: use |
| 7 | +GitHub or other public site, or setup/use your own repository. |
| 8 | + |
| 9 | +While you can use a private repository and utilize ``git format-patch`` to |
| 10 | +submit patches, this is discouraged as it does not facilitate public peer |
| 11 | +review. |
| 12 | + |
| 13 | +### Option 1: GitHub |
| 14 | + |
| 15 | +1. Setup a GitHub account (http://github.com/), if you haven't yet |
| 16 | +2. Fork the ZF1 repository (http://github.com/zendframework/zf1) |
| 17 | +3. Clone your fork locally and enter it (use your own GitHub username |
| 18 | + in the statement below) |
| 19 | + |
| 20 | + ```sh |
| 21 | + % git clone git@github.com:<username>/zf1.git |
| 22 | + % cd zf1 |
| 23 | + ``` |
| 24 | + |
| 25 | +4. Add a remote to the canonical ZF repository, so you can keep your fork |
| 26 | + up-to-date: |
| 27 | + |
| 28 | + ```sh |
| 29 | + % git remote add zf1 https://github.com/zendframework/zf1.git |
| 30 | + % git fetch zf1 |
| 31 | + ``` |
| 32 | + |
| 33 | +### Option 2: Personal Repository |
| 34 | + |
| 35 | +We assume you will use gitosis (http://git-scm.com/book/en/Git-on-the-Server-Gitosis) |
| 36 | +or gitolite (http://git-scm.com/book/en/Git-on-the-Server-Gitolite) to host your |
| 37 | +own repository. If you go this route, we will assume you have the knowledge to |
| 38 | +do so, or know where to obtain it. We will not assist you in setting up such a |
| 39 | +repository. |
| 40 | + |
| 41 | +1. Create a new repository |
| 42 | + |
| 43 | + ```sh |
| 44 | + % git init |
| 45 | + ``` |
| 46 | + |
| 47 | +2. Add an "origin" remote pointing to your gitosis/gitolite repo: |
| 48 | + |
| 49 | + ```sh |
| 50 | + % git remote add origin git://yourdomain/yourrepo.git |
| 51 | + ``` |
| 52 | + |
| 53 | +3. Add a remote for the ZF repository and fetch it |
| 54 | + |
| 55 | + ```sh |
| 56 | + % git remote add zf1 https://github.com/zendframework/zf1.git |
| 57 | + % git fetch zf1 |
| 58 | + ``` |
| 59 | + |
| 60 | +4. Create a new branch for the ZF repository (named "zf/master" here) |
| 61 | + |
| 62 | + ```sh |
| 63 | + % git checkout -b zf/master zf1/master |
| 64 | + ``` |
| 65 | + |
| 66 | +5. Create your master branch off the ZF branch, and push to your |
| 67 | + repository |
| 68 | + |
| 69 | + ```sh |
| 70 | + % git checkout -b master |
| 71 | + % git push origin HEAD:master |
| 72 | + ``` |
| 73 | + |
| 74 | +## Contributor License Agreement and your git configuration |
| 75 | + |
| 76 | +In order for us to accept your changes to Zend Framework 1.X, you must sign and |
| 77 | +return a Contributors License Agreement (http://framework.zend.com/cla or |
| 78 | +http://framework.zend.com/ccla). For us to verify that you have a CLA on file, |
| 79 | +we need you to do one of the following: |
| 80 | + |
| 81 | +* If your github username matches the username with which you registered on the |
| 82 | + former Zend Framework issue tracker (our old JIRA instance), we should be able |
| 83 | + to look you up fine. |
| 84 | +* Otherwise, please ensure that you set your user email in your working |
| 85 | + directory to match the email we have on file with your CLA. This can be done |
| 86 | + with the following |
| 87 | + |
| 88 | + ```sh |
| 89 | + % git config user.email "your-email@example.org" |
| 90 | + ``` |
| 91 | + |
| 92 | + We can then look up your CLA status based on your commits. |
| 93 | + |
| 94 | +If we cannot determine your CLA status, we will ask in a comment on the pull |
| 95 | +request for either your username or email. |
| 96 | + |
| 97 | +## Keeping Up-to-Date |
| 98 | + |
| 99 | +Periodically, you should update your fork or personal repository to |
| 100 | +match the canonical ZF repository. In each of the above setups, we have |
| 101 | +added a remote to the Zend Framework repository, which allows you to do |
| 102 | +the following: |
| 103 | + |
| 104 | + |
| 105 | +```sh |
| 106 | +% git checkout master |
| 107 | +% git pull zf1 master |
| 108 | +- OPTIONALLY, to keep your remote up-to-date - |
| 109 | +% git push origin |
| 110 | +``` |
| 111 | + |
| 112 | +## Working on Zend Framework |
| 113 | + |
| 114 | +When working on Zend Framework, we recommend you do each new feature or |
| 115 | +bugfix in a new branch. This simplifies the task of code review as well |
| 116 | +as of merging your changes into the canonical repository. |
| 117 | + |
| 118 | +A typical work flow will then consist of the following: |
| 119 | + |
| 120 | +1. Create a new local branch based off your master branch. |
| 121 | +2. Switch to your new local branch. (This step can be combined with the |
| 122 | + previous step with the use of `git checkout -b`.) |
| 123 | +3. Do some work, commit, repeat as necessary. |
| 124 | +4. Push the local branch to your remote repository. |
| 125 | +5. Send a pull request. |
| 126 | + |
| 127 | +The mechanics of this process are actually quite trivial. Below, we will |
| 128 | +create a branch for fixing an issue in the tracker. |
| 129 | + |
| 130 | +```sh |
| 131 | +% git checkout -b zf9295 |
| 132 | +Switched to a new branch 'zf9295' |
| 133 | +``` |
| 134 | +... do some work ... |
| 135 | + |
| 136 | +```sh |
| 137 | +% git commit |
| 138 | +``` |
| 139 | +... write your log message ... |
| 140 | + |
| 141 | +```sh |
| 142 | +% git push origin HEAD:zf9295 |
| 143 | +Counting objects: 38, done. |
| 144 | +Delta compression using up to 2 threads. |
| 145 | +Compression objects: 100% (18/18), done. |
| 146 | +Writing objects: 100% (20/20), 8.19KiB, done. |
| 147 | +Total 20 (delta 12), reused 0 (delta 0) |
| 148 | +To ssh://git@github.com/weierophinney/zf1.git |
| 149 | + b5583aa..4f51698 HEAD -> master |
| 150 | +``` |
| 151 | + |
| 152 | + |
| 153 | +To send a pull request, you have two options. |
| 154 | + |
| 155 | +If using GitHub, you can do the pull request from there. Navigate to |
| 156 | +your repository, select the branch you just created, and then select the |
| 157 | +"Pull Request" button in the upper right. Select the user |
| 158 | +"zendframework" as the recipient. |
| 159 | + |
| 160 | +If using your own repository - or even if using GitHub - you can send an |
| 161 | +email indicating you have changes to pull: |
| 162 | + |
| 163 | +- Send to <zf-devteam@zend.com> |
| 164 | + |
| 165 | +- In your message, specify: |
| 166 | + - The URL to your repository (e.g., `git://mwop.net/zf1.git`) |
| 167 | + - The branch containing the changes you want pulled (e.g., `zf9295`) |
| 168 | + - The nature of the changes (e.g., `implements |
| 169 | + Zend_Service_Twitter`, `fixes ZF-9295`, etc.) |
| 170 | + |
| 171 | +### What branch to issue the pull request against? |
| 172 | + |
| 173 | +Which branch should you issue a pull request against? |
| 174 | + |
| 175 | +- For fixes against the stable release, issue the pull request against the |
| 176 | + "master" branch. |
| 177 | +- For new features, or fixes that introduce new elements to the public API (such |
| 178 | + as new public methods or properties), issue the pull request against the |
| 179 | + "develop" branch. |
| 180 | + |
| 181 | +## Branch Cleanup |
| 182 | + |
| 183 | +As you might imagine, if you are a frequent contributor, you'll start to |
| 184 | +get a ton of branches both locally and on your remote. |
| 185 | + |
| 186 | +Once you know that your changes have been accepted to the master |
| 187 | +repository, we suggest doing some cleanup of these branches. |
| 188 | + |
| 189 | +- Local branch cleanup |
| 190 | + |
| 191 | + ```sh |
| 192 | + % git branch -d <branchname> |
| 193 | + ``` |
| 194 | + |
| 195 | +- Remote branch removal |
| 196 | + |
| 197 | + ```sh |
| 198 | + % git push origin :<branchname> |
| 199 | + ``` |
| 200 | + |
| 201 | +## FEEDS AND EMAILS |
| 202 | + |
| 203 | +RSS feeds may be found at: |
| 204 | + |
| 205 | +- `https://github.com/zendframework/zf1/commits/<branch>.atom` |
| 206 | + |
| 207 | +where <branch> is a branch in the repository. |
| 208 | + |
| 209 | +To subscribe to git email notifications, simply watch or fork the zf1 repository |
| 210 | +on GitHub. |
| 211 | + |
| 212 | +## CONTRIBUTORS AND COMMITTERS |
| 213 | + |
| 214 | +Both Zend's internal Zend Framework team and the members of the Community Review |
| 215 | +team have push privileges to the ZF1 repository. Additionally, a number of |
| 216 | +members of the community have been vetted to merge pull requests. When in doubt, |
| 217 | +hop into Freenode IRC, and ask in the #zftalk.dev channel for somebody to review |
| 218 | +and/or merge your change. |
0 commit comments