Skip to content
Newer
Older
100644 226 lines (160 sloc) 9.36 KB
1d891f0 @willdurand Added documentation to Propel2
willdurand authored Nov 10, 2011
1 ---
2 layout: default
3 title: How To Contribute ?
4 ---
5
6 # How To Contribute ? #
7
8 You can easily contribute to the Propel project since all projects are hosted by [GitHub](https://github.com).
9 You just have to _fork_ the Propel project on the [PropelORM organization](https://github.com/propelorm) and
10 to provide Pull Requests or to submit issues. Note, we are using [Git](http://git-scm.com) as main Source Code Management.
11
12 The Propel organization maintains four projects:
13
14 * [Propel](http://github.com/propelorm/Propel) : the main project.
15 * [PropelBundle](http://github.com/propelorm/PropelBundle) : a bundle to integrate Propel with [Symfony2](http://www.symfony.com).
16 * [sfPropelORMPlugin](http://github.com/propelorm/sfPropelORMPlugin) : a plugin to integrate Propel with [symfony 1.x](http://www.symfony-project.org);
17 * [propelorm.github.com](https://github.com/propelorm/propelorm.github.com) : the Propel documentation (aka this website).
18
19 ## Submit an issue ##
20
21 The ticketing system is also hosted on GitHub:
22
23 * Propel: [https://github.com/propelorm/Propel/issues](https://github.com/propelorm/Propel/issues)
24 * PropelBundle: [https://github.com/propelorm/PropelBundle/issues](https://github.com/propelorm/PropelBundle/issues)
25 * sfPropelORMPlugin: [https://github.com/propelorm/sfPropelORMPlugin/issues](https://github.com/propelorm/sfPropelORMPlugin/issues)
26
27 ## Make a Pull Request ##
28
29 The best way to submit a patch is to make a Pull Request on GitHub. First, you should create a new branch from the `master`.
30 Assuming you are in your local Propel project:
31
32 {% highlight bash %}
33 > git checkout -b master fix-my-patch
34 {% endhighlight %}
35
36 Now you can write your patch in this branch. Don't forget to provide unit tests with your fix to prove both the bug and the patch.
37 It will ease the process to accept or refuse a Pull Request.
38
39 When you're done, you have to rebase your branch to provide a clean and safe Pull Request.
40
41 {% highlight bash %}
42 > git checkout master
43 > git pull --ff-only upstream master
44 > git checkout fix-my-patch
45 > git rebase master
46 {% endhighlight %}
47
48 In this example, the `upstream` remote is the PropelORM organization repository.
49
50 Once done, you can submit the Pull Request by pushing your branch to your fork:
51
52 {% highlight bash %}
53 > git push origin fix-my-patch
54 {% endhighlight %}
55
56 Go to www.github.com and press the _Pull Request_ button. Add a short description to this Pull Request and submit it.
57
58 ## Running Unit Tests ##
59
60 Propel uses [PHPUnit](http://www.phpunit.de) to test the build and runtime frameworks.
61
62 You can find the unit test classes and support files in the `test/testsuite` directory.
63
64 ### Install PHPUnit ###
65
66 In order to run the tests, you must install PHPUnit:
67
68 {% highlight bash %}
69 > pear channel-discover pear.phpunit.de
70 > pear install phpunit/PHPUnit
71 {% endhighlight %}
72
73 ### Configure the Database to be Used in the Tests ###
74
75 You must configure both the generator and the runtime connection settings.
76
77 {% highlight ini %}
78 // in test/fixtures/bookstore/build.properties
79 propel.database = mysql
80 propel.database.url = mysql:dbname=test
81 propel.mysqlTableType = InnoDB
82 propel.disableIdentifierQuoting=true
83 # For MySQL or Oracle, you also need to specify username & password
84 propel.database.user = myusername
85 propel.database.password = p@ssw0rd
86 {% endhighlight %}
87
88 {% highlight xml %}
89 // in test/fixtures/bookstore/runtime-conf.xml
90 <datasource id="bookstore">
91 <!-- the Propel adapter to use for this connection -->
92 <adapter>mysql</adapter>
93 <!-- Connection parameters. See PDO documentation for DSN format and available option constants. -->
94 <connection>
95 <classname>DebugPDO</classname>
96 <dsn>mysql:dbname=test</dsn>
97 <user>myusername</user>
98 <password>p@ssw0rd</password>
99 <options>
100 <option id="ATTR_PERSISTENT">false</option>
101 </options>
102 <attributes>
103 <!-- For MySQL, you should also turn on prepared statement emulation,
104 as prepared statements support is buggy in mysql driver -->
105 <option id="ATTR_EMULATE_PREPARES">true</option>
106 </attributes>
107 <settings>
108 <!-- Set the character set for client connection -->
109 <setting id="charset">utf8</setting>
110 </settings>
111 </connection>
112 </datasource>
113 {% endhighlight %}
114
115 >**Tip**<br />To run the unit tests for the namespace support in PHP 5.3, you must also configure the `fixtures/namespaced` project.
116
117 <br />
118
119 >**Tip**<br />To run the unit tests for the database schema support, you must also configure the `fixtures/schemas` project. This projects requires that your database supports schemas, and already contains the following schemas: `bookstore_schemas`, `contest`, and `second_hand_books`. Note that the user defined in `build.properties` and `runtime-conf.xml` must have access to these schemas.
120
121 ### Build the Propel Model and Initialize the Database ###
122
123 {% highlight bash %}
124 > cd /path/to/propel/test
125 > ../generator/bin/propel-gen fixtures/bookstore main
126 > mysqladmin create test
127 > ../generator/bin/propel-gen fixtures/bookstore insert-sql
128 {% endhighlight %}
129
130 >**Tip**<br />To run the unit tests for the namespace support in PHP 5.3, you must also build the `fixtures/namespaced/` project.
131
132 <br />
133
134 >**Tip**<br />To run the unit tests for the database schema support, you must also build the `fixtures/schemas/` project.
135
136 If you test on MySQL, the following SQL script will create all the necessary test databases and grant access to the anonymous user, so the unit tests should pass without any special configuration:
137
138 {% highlight sql %}
139 CREATE DATABASE test;
140 GRANT ALL ON test.* TO ''@'localhost';
141
142 CREATE DATABASE bookstore_schemas;
143 GRANT ALL ON bookstore_schemas.* TO ''@'localhost';
144
145 CREATE DATABASE contest;
146 GRANT ALL ON contest.* TO ''@'localhost';
147
148 CREATE DATABASE second_hand_books;
149 GRANT ALL ON second_hand_books.* TO ''@'localhost';
150
151 CREATE DATABASE reverse_bookstore;
152 GRANT ALL ON reverse_bookstore.* TO ''@'localhost';
153 {% endhighlight %}
154
155 You can build all fixtures by running the `reset_tests.sh` shell script:
156
157 {% highlight bash %}
158 > cd /path/to/propel/test
159 > ./reset_tests.sh
160 {% endhighlight %}
161
162 ### Run the Unit Tests ###
163
164 Run all the unit tests at once using the `phpunit` command:
165
166 {% highlight bash %}
167 > cd /path/to/propel/test
168 > phpunit testsuite
169 {% endhighlight %}
170
171 >**Warning**<br />The `testsuite/generator/builder/NamespaceTest.php` file uses PHP 5.3 namespaces, and therefore will create a parse error under PHP 5.2. To launch the unit test suite in a PHP 5.2 platform, simply delete this test file.
172
173 To run a single test, go inside the unit test directory, and run the test using the command line. For example to run only GeneratedObjectTest:
174
175 {% highlight bash %}
176 > cd testsuite/generator/builder/om
177 > phpunit GeneratedObjectTest
178 {% endhighlight %}
179
180 ### How the Tests Work ###
181
182 Every method in the test classes that begins with 'test' is run as a test case by PHPUnit. All tests are run in isolation; the `setUp()` method is called at the beginning of ''each'' test and the `tearDown()` method is called at the end.
183
184 The `BookstoreTestBase` class specifies `setUp()` and `tearDown()` methods which populate and depopulate, respectively, the database. This means that every unit test is run with a cleanly populated database. To see the sample data that is populated, take a look at the `BookstoreDataPopulator` class. You can also add data to this class, if needed by your tests; however, proceed cautiously when changing existing data in there as there may be unit tests that depend on it. More typically, you can simply create the data you need from within your test method. It will be deleted by the `tearDown()` method, so no need to clean up after yourself.
185
186 ## Writing Tests ##
187
188 If you've made a change to a template or to Propel behavior, the right thing to do is write a unit test that ensures that it works properly -- and continues to work in the future.
189
190 Writing a unit test often means adding a method to one of the existing test classes. For example, let's test a feature in the Propel templates that supports saving of objects when only default values have been specified. Just add a `testSaveWithDefaultValues()` method to the `GeneratedObjectTest` class, as follows:
191
192 {% highlight php %}
193 <?php
194
195 /**
196 * Test saving object when only default values are set.
197 */
198 public function testSaveWithDefaultValues() {
199
200 // Relies on a default value of 'Penguin' specified in schema
201 // for publisher.name col.
202
203 $pub = new Publisher();
204 $pub->setName('Penguin');
205 // in the past this wouldn't have marked object as modified
206 // since 'Penguin' is the value that's already set for that attrib
207 $pub->save();
208
209 // if getId() returns the new ID, then we know save() worked.
210 $this->assertNotNull($pub->getId(), "Expect Publisher->save() to work with only default values.");
211 }
212 ?>
213 {% endhighlight %}
214
215 Run the test again using the command line to check that it passes:
216
217 {% highlight bash %}
218 > phpunit GeneratedObjectTest
219 {% endhighlight %}
220
221 You can also write additional unit test classes to any of the directories in `test/testsuite/` (or add new directories if needed). The `phpunit` command will find these files automatically and run them.
222
223 ## Improve the documentation ##
224
225 The Propel documentation is written in [Markdown](http://daringfireball.net/projects/markdown/) syntax and runs through [GitHub Pages](http://pages.github.com/). Everybody can contribute to the documentation by forking the [propelorm.github.com](https://github.com/propelorm/propelorm.github.com) project and to submit Pull Requests.
Something went wrong with that request. Please try again.