Skip to content

Latest commit

 

History

History
225 lines (160 loc) · 9.36 KB

contribute.markdown

File metadata and controls

225 lines (160 loc) · 9.36 KB
Raw
layout title
default
How To Contribute ?

How To Contribute ?

You can easily contribute to the Propel project since all projects are hosted by GitHub. You just have to fork the Propel project on the PropelORM organization and to provide Pull Requests or to submit issues. Note, we are using Git as main Source Code Management.

The Propel organization maintains four projects:

Submit an issue

The ticketing system is also hosted on GitHub:

Make a Pull Request

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. Assuming you are in your local Propel project:

{% highlight bash %}

git checkout -b master fix-my-patch {% endhighlight %}

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. It will ease the process to accept or refuse a Pull Request.

When you're done, you have to rebase your branch to provide a clean and safe Pull Request.

{% highlight bash %}

git checkout master git pull --ff-only upstream master git checkout fix-my-patch git rebase master {% endhighlight %}

In this example, the upstream remote is the PropelORM organization repository.

Once done, you can submit the Pull Request by pushing your branch to your fork:

{% highlight bash %}

git push origin fix-my-patch {% endhighlight %}

Go to www.github.com and press the Pull Request button. Add a short description to this Pull Request and submit it.

Running Unit Tests

Propel uses PHPUnit to test the build and runtime frameworks.

You can find the unit test classes and support files in the test/testsuite directory.

Install PHPUnit

In order to run the tests, you must install PHPUnit:

{% highlight bash %}

pear channel-discover pear.phpunit.de pear install phpunit/PHPUnit {% endhighlight %}

Configure the Database to be Used in the Tests

You must configure both the generator and the runtime connection settings.

{% highlight ini %} // in test/fixtures/bookstore/build.properties propel.database = mysql propel.database.url = mysql:dbname=test propel.mysqlTableType = InnoDB propel.disableIdentifierQuoting=true

For MySQL or Oracle, you also need to specify username & password

propel.database.user = myusername propel.database.password = p@ssw0rd {% endhighlight %}

{% highlight xml %} // in test/fixtures/bookstore/runtime-conf.xml

mysql

DebugPDO mysql:dbname=test myusername p@ssw0rd false true utf8 {% endhighlight %}

Tip
To run the unit tests for the namespace support in PHP 5.3, you must also configure the fixtures/namespaced project.


Tip
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.

Build the Propel Model and Initialize the Database

{% highlight bash %}

cd /path/to/propel/test ../generator/bin/propel-gen fixtures/bookstore main mysqladmin create test ../generator/bin/propel-gen fixtures/bookstore insert-sql {% endhighlight %}

Tip
To run the unit tests for the namespace support in PHP 5.3, you must also build the fixtures/namespaced/ project.


Tip
To run the unit tests for the database schema support, you must also build the fixtures/schemas/ project.

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:

{% highlight sql %} CREATE DATABASE test; GRANT ALL ON test.* TO ''@'localhost';

CREATE DATABASE bookstore_schemas; GRANT ALL ON bookstore_schemas.* TO ''@'localhost';

CREATE DATABASE contest; GRANT ALL ON contest.* TO ''@'localhost';

CREATE DATABASE second_hand_books; GRANT ALL ON second_hand_books.* TO ''@'localhost';

CREATE DATABASE reverse_bookstore; GRANT ALL ON reverse_bookstore.* TO ''@'localhost'; {% endhighlight %}

You can build all fixtures by running the reset_tests.sh shell script:

{% highlight bash %}

cd /path/to/propel/test ./reset_tests.sh {% endhighlight %}

Run the Unit Tests

Run all the unit tests at once using the phpunit command:

{% highlight bash %}

cd /path/to/propel/test phpunit testsuite {% endhighlight %}

Warning
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.

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:

{% highlight bash %}

cd testsuite/generator/builder/om phpunit GeneratedObjectTest {% endhighlight %}

How the Tests Work

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.

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.

Writing Tests

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.

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:

{% highlight php %}

setName('Penguin'); // in the past this wouldn't have marked object as modified // since 'Penguin' is the value that's already set for that attrib $pub->save(); // if getId() returns the new ID, then we know save() worked. $this->assertNotNull($pub->getId(), "Expect Publisher->save() to work with only default values."); } ?>

{% endhighlight %}

Run the test again using the command line to check that it passes:

{% highlight bash %}

phpunit GeneratedObjectTest {% endhighlight %}

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.

Improve the documentation

The Propel documentation is written in Markdown syntax and runs through GitHub Pages. Everybody can contribute to the documentation by forking the propelorm.github.com project and to submit Pull Requests.