README-GIT.md
1# USING THE GIT REPOSITORY
2
3## Setup your own public repository
4
5Your first step is to establish a public repository from which we can
6pull your work into the master repository. You have two options: use
7GitHub or other public site, or setup/use your own repository.
8
9While you can use a private repository and utilize ``git format-patch`` to
10submit patches, this is discouraged as it does not facilitate public peer
11review.
12
13### Option 1: GitHub
14
15 1. Setup a GitHub account (http://github.com/), if you haven't yet
16 2. Fork the ZF2 repository (http://github.com/zendframework/zf2)
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>/zf2.git
22 % cd zf2
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 zf2 https://github.com/zendframework/zf2.git
30 % git fetch zf2
31 ```
32
33### Option 2: Personal Repository
34
35We assume you will use gitosis (http://git-scm.com/book/en/Git-on-the-Server-Gitosis)
36or gitolite (http://git-scm.com/book/en/Git-on-the-Server-Gitolite) to host your
37own repository. If you go this route, we will assume you have the knowledge to
38do so, or know where to obtain it. We will not assist you in setting up such a
39repository.
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 zf2 https://github.com/zendframework/zf2.git
57 % git fetch zf2
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 zf2/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### Pre-Commit Hook (Optional)
75
76The ZF2 Travis-CI will confirm that code style standards are met
77by using ```php-cs-fixer``` (https://github.com/FriendsOfPHP/PHP-CS-Fixer) during its build runs.
78
79To reduce the number of red Travis-CI builds, the following Git pre-commit hook
80can help catch code style issues before committing. Save it as
81```.git/hooks/pre-commit```, and make sure it is executable.
82
83```php
84#!/usr/bin/env php
85<?php
86/**
87 * .git/hooks/pre-commit
88 *
89 * This pre-commit hooks will check for PHP errors (lint), and make sure the
90 * code is PSR-2 compliant.
91 *
92 * Dependency: PHP-CS-Fixer (https://github.com/FriendsOfPHP/PHP-CS-Fixer)
93 *
94 * @author Mardix http://github.com/mardix
95 * @author Matthew Weier O'Phinney http://mwop.net/
96 * @since 4 Sept 2012
97 */
98
99$exit = 0;
100
101/*
102 * collect all files which have been added, copied or
103 * modified and store them in an array called output
104 */
105$output = array();
106exec('git diff --cached --name-status --diff-filter=ACM', $output);
107
108foreach ($output as $file) {
109 if ('D' === substr($file, 0, 1)) {
110 // deleted file; do nothing
111 continue;
112 }
113
114 $fileName = trim(substr($file, 1));
115
116 /*
117 * Only PHP files
118 */
119 $extension = pathinfo($fileName, PATHINFO_EXTENSION);
120 if (!preg_match('/^ph(p|tml)$/', $extension)) {
121 continue;
122 }
123
124 /*
125 * Check for parse errors
126 */
127 $output = array();
128 $return = 0;
129 exec("php -l " . escapeshellarg($fileName), $output, $return);
130
131 if ($return != 0) {
132 echo "PHP file fails to parse: " . $fileName . ":" . PHP_EOL;
133 echo implode(PHP_EOL, $output) . PHP_EOL;
134 $exit = 1;
135 continue;
136 }
137
138 /*
139 * PHP-CS-Fixer
140 */
141 $output = array();
142 $return = null;
143 exec("php-cs-fixer fix --dry-run --level=psr2 " . escapeshellarg($fileName), $output, $return);
144 if ($return != 0 || !empty($output)) {
145 echo "PHP file contains CS issues: " . $fileName . ":" . PHP_EOL;
146 echo implode(PHP_EOL, $output) . PHP_EOL;
147 $exit = 1;
148 continue;
149 }
150}
151
152exit($exit);
153```
154
155## Keeping Up-to-Date
156
157Periodically, you should update your fork or personal repository to
158match the canonical ZF repository. In each of the above setups, we have
159added a remote to the Zend Framework repository, which allows you to do
160the following:
161
162
163```sh
164% git checkout master
165% git pull zf2 master
166- OPTIONALLY, to keep your remote up-to-date -
167% git push origin
168```
169
170If you're tracking other branches -- for example, the "develop" branch, where
171new feature development occurs -- you'll want to do the same operations for that
172branch; simply substitute "develop" for "master".
173
174## Working on Zend Framework
175
176When working on Zend Framework, we recommend you do each new feature or
177bugfix in a new branch. This simplifies the task of code review as well
178as of merging your changes into the canonical repository.
179
180A typical work flow will then consist of the following:
181
182 1. Create a new local branch based off your master branch.
183 2. Switch to your new local branch. (This step can be combined with the
184 previous step with the use of `git checkout -b`.)
185 3. Do some work, commit, repeat as necessary.
186 4. Push the local branch to your remote repository.
187 5. Send a pull request.
188
189The mechanics of this process are actually quite trivial. Below, we will
190create a branch for fixing an issue in the tracker.
191
192```sh
193% git checkout -b zf9295
194Switched to a new branch 'zf9295'
195```
196... do some work ...
197
198```sh
199% git commit
200```
201... write your log message ...
202
203```sh
204% git push origin HEAD:zf9295
205Counting objects: 38, done.
206Delta compression using up to 2 threads.
207Compression objects: 100% (18/18), done.
208Writing objects: 100% (20/20), 8.19KiB, done.
209Total 20 (delta 12), reused 0 (delta 0)
210To ssh://git@github.com/weierophinney/zf2.git
211 b5583aa..4f51698 HEAD -> master
212```
213
214
215To send a pull request, you have two options.
216
217If using GitHub, you can do the pull request from there. Navigate to
218your repository, select the branch you just created, and then select the
219"Pull Request" button in the upper right. Select the user
220"zendframework" as the recipient.
221
222If using your own repository - or even if using GitHub - you can send an
223email indicating you have changes to pull:
224
225 - Send to <zf-devteam@zend.com>
226
227 - In your message, specify:
228 - The URL to your repository (e.g., `git://mwop.net/zf2.git`)
229 - The branch containing the changes you want pulled (e.g., `zf9295`)
230 - The nature of the changes (e.g., `implements
231 Zend_Service_Twitter`, `fixes ZF-9295`, etc.)
232
233### What branch to issue the pull request against?
234
235Which branch should you issue a pull request against?
236
237- For fixes against the stable release, issue the pull request against the
238 "master" branch.
239- For new features, or fixes that introduce new elements to the public API (such
240 as new public methods or properties), issue the pull request against the
241 "develop" branch.
242
243## Branch Cleanup
244
245As you might imagine, if you are a frequent contributor, you'll start to
246get a ton of branches both locally and on your remote.
247
248Once you know that your changes have been accepted to the master
249repository, we suggest doing some cleanup of these branches.
250
251 - Local branch cleanup
252
253 ```sh
254 % git branch -d <branchname>
255 ```
256
257 - Remote branch removal
258
259 ```sh
260 % git push origin :<branchname>
261 ```
262
263
264## FEEDS AND EMAILS
265
266RSS feeds may be found at:
267
268`https://github.com/zendframework/zf2/commits/<branch>.atom`
269
270where <branch> is a branch in the repository.
271
272To subscribe to git email notifications, simply watch or fork the zf2 repository
273on GitHub.
274
275## CONTRIBUTORS AND COMMITTERS
276
277Both Zend's internal Zend Framework team and the members of the Community Review
278team have push privileges to the ZF2 repository.
279
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}