Skip to content

Commit

Permalink
Update the contribution guideline
Browse files Browse the repository at this point in the history 
Since the new repository's design, the process to create a pull request
has been a little bit change ; update the documentation to match the
actual one.

Also remove the contribution part in the README file and move it to the
contributing file. The README was up to date with the new testing
process.

Also update the part about fixing checkstyle. To keep clean logs and
make git blame easier, we should only fix files which have been changed.
  • Loading branch information
@robin850
robin850 committed Oct 21, 2013
1 parent f28f53a commit 815f8a0
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 162 deletions.
60 changes: 1 addition & 59 deletions README.md
View file
Expand Up @@ -31,65 +31,7 @@ Read the [Propel documentation](http://www.propelorm.org/).
Everybody can contribute to Propel2. Just fork it, and send Pull Requests.
You have to follow [Propel2 Coding Standards](https://github.com/propelorm/Propel2/wiki/Coding-Standards) and provides unit tests as much as possible.

**Note:** you can fix checkstyle before to submit a Pull Request by using the Symfony2 [php-cs-fixer](http://cs.sensiolabs.org/) script.
You just need to install the script:

wget http://cs.sensiolabs.org/get/php-cs-fixer.phar

Then use it:

php php-cs-fixer.phar fix .


## Unit Tests ##

To run unit tests, you'll have to install vendors by using [**Composer**](https://github.com/composer/composer).
If you don't have an available `composer.phar` command, just download it:

wget http://getcomposer.org/composer.phar

If you haven't wget on your computer, use `curl` instead:

curl -s http://getcomposer.org/installer | php

Then, install dependencies:

php composer.phar install --dev


#### MySQL ####

The Propel test suite requires a database (`test` for instance, but feel free to choose the name you want), and
three database schemas: `bookstore_schemas`, `contest`, and `second_hand_books`.

Here is the set of commands to run in order to setup MySQL:

mysql -uroot -e 'SET FOREIGN_KEY_CHECKS = 0; DROP DATABASE IF EXISTS test; DROP SCHEMA IF EXISTS second_hand_books; DROP SCHEMA IF EXISTS contest; DROP SCHEMA IF EXISTS bookstore_schemas; SET FOREIGN_KEY_CHECKS = 1;'
mysql -uroot -e 'CREATE DATABASE test; CREATE SCHEMA bookstore_schemas; CREATE SCHEMA contest; CREATE SCHEMA second_hand_books;'

Once done, build fixtures (default vendor is `mysql`):

bin/propel test:prepare

To match Travis CI MySQL configuration, you must set `@@sql_mode` to `STRICT_ALL_TABLES` in yours.

#### PostgreSQL ####

Create mandatory databases, then run:

bin/propel test:prepare --vendor=pgsql --dsn="pgsql:dbname=test" --user="postgres"

#### SQLite ####

There is nothing to setup, just run:

bin/propel test:prepare --vendor=sqlite --dsn="sqlite:/tmp/database.sqlite" --user="" --password=""


Now you can run the test suite by running:

phpunit

Please see our [contribution guideline](https://github.com/propelorm/Propel2/blob/master/documentation/contribute.markdown). Thank you!

## License ##

Expand Down
165 changes: 62 additions & 103 deletions documentation/contribute.markdown
View file
Expand Up @@ -28,20 +28,23 @@ 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](https://help.github.com/articles/creating-a-pull-request).
The best way to submit a patch is to [make a Pull Request on GitHub](https://help.github.com/articles/creating-a-pull-request).
First, you should create a new branch from the `master`.
Assuming you are in your local Propel project:

```bash
$ git checkout -b master fix-my-patch
```

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.
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.
When you're done, you have to rebase your branch to provide a clean and safe Pull
Request.

```bash
$ git remote add upstream https://github.com/propelorm/Propel2
$ git checkout master
$ git pull --ff-only upstream master
$ git checkout fix-my-patch
Expand All @@ -56,127 +59,63 @@ Once done, you can submit the Pull Request by pushing your branch to your fork:
$ git push origin fix-my-patch
```

Go to www.github.com and press the _Pull Request_ button. Add a short description to this Pull Request and submit it.
Go to your fork of the project on GitHub and switch to the patched branch (here
in the above example, `fix-my-patch`) and click on the "Compare and pull request"
button. Add a short description to this Pull Request and submit it.

## Running Unit Tests ##

Propel uses [PHPUnit](http://www.phpunit.de) to test the build and runtime frameworks.
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.
You can find the unit test classes and support files in the `tests/` directory.

### Install PHPUnit ###
### Install Composer ###

In order to run the tests, you must install PHPUnit:
In order to run the tests, you must install the development dependencies. Propel
uses [Composer][] to manage its dependencies. To install it, you are done with:

```bash
$ pear channel-discover pear.phpunit.de
$ pear install phpunit/PHPUnit
```

### Configure the Database to be Used in the Tests ###

You must configure both the generator and the runtime connection settings.
$ wget http://getcomposer.org/composer.phar

```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
```

```xml
// in test/fixtures/bookstore/runtime-conf.xml
<datasource id="bookstore">
<!-- the Propel adapter to use for this connection -->
<adapter>mysql</adapter>
<!-- Connection parameters. See PDO documentation for DSN format and available option constants. -->
<connection>
<classname>DebugPDO</classname>
<dsn>mysql:dbname=test</dsn>
<user>myusername</user>
<password>p@ssw0rd</password>
<options>
<option id="ATTR_PERSISTENT">false</option>
</options>
<attributes>
<!-- For MySQL, you should also turn on prepared statement emulation,
as prepared statements support is buggy in mysql driver -->
<option id="ATTR_EMULATE_PREPARES">true</option>
</attributes>
<settings>
<!-- Set the character set for client connection -->
<setting id="charset">utf8</setting>
</settings>
</connection>
</datasource>
```
Or if you don't have `wget` on your machine:

>**Tip**<br />To run the unit tests for the namespace support in PHP 5.3, you must also configure the `fixtures/namespaced` project.
$ curl -s http://getcomposer.org/installer | php

<br />
Then run Composer to install the necessary stuff:

>**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.
$ php composer.phar install --dev

### Build the Propel Model and Initialize the Database ###
#### Setup MySQL ####

```bash
$ cd /path/to/propel/test
$ ../bin/propel/propel-gen fixtures/bookstore main
$ mysqladmin create test
$ ../generator/bin/propel-gen fixtures/bookstore insert-sql
```
The Propel test suite requires a database (`test` for instance, but feel free to
choose the name you want), and three database schemas: `bookstore_schemas`,
`contest`, and `second_hand_books`.

>**Tip**<br />To run the unit tests for the namespace support in PHP 5.3, you must also build the `fixtures/namespaced/` project.
Here is the set of commands to run in order to setup MySQL:

<br />
$ mysql -uroot -e 'SET FOREIGN_KEY_CHECKS = 0; DROP DATABASE IF EXISTS test; DROP SCHEMA IF EXISTS second_hand_books; DROP SCHEMA IF EXISTS contest; DROP SCHEMA IF EXISTS bookstore_schemas; SET FOREIGN_KEY_CHECKS = 1;'
$ mysql -uroot -e 'CREATE DATABASE test; CREATE SCHEMA bookstore_schemas; CREATE SCHEMA contest; CREATE SCHEMA second_hand_books;'

>**Tip**<br />To run the unit tests for the database schema support, you must also build the `fixtures/schemas/` project.
Once done, build fixtures (default vendor is `mysql`):

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:
$ bin/propel test:prepare

```sql
CREATE DATABASE test;
GRANT ALL ON test.* TO ''@'localhost';
To match Travis CI MySQL configuration, you must set `@@sql_mode` to `STRICT_ALL_TABLES` in yours.

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

CREATE DATABASE contest;
GRANT ALL ON contest.* TO ''@'localhost';
Create mandatory databases, then run:

CREATE DATABASE second_hand_books;
GRANT ALL ON second_hand_books.* TO ''@'localhost';
$ bin/propel test:prepare --vendor=pgsql --dsn="pgsql:dbname=test" --user="postgres"

CREATE DATABASE reverse_bookstore;
GRANT ALL ON reverse_bookstore.* TO ''@'localhost';
```
#### For SQLite ####

You can build all fixtures by running the `reset_tests.sh` shell script:
There is nothing to setup, just run:

```bash
$ cd /path/to/propel/test
$ ./reset_tests.sh
```
$ bin/propel test:prepare --vendor=sqlite --dsn="sqlite:/tmp/database.sqlite" --user="" --password=""

### Run the Unit Tests ###
Now you can run the test suite by running:

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

```bash
$ cd /path/to/propel/test
$ phpunit testsuite
```

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:

```
$ cd testsuite/generator/builder/om
$ phpunit GeneratedObjectTest
```
$ phpunit

### How the Tests Work ###

Expand Down Expand Up @@ -215,12 +154,32 @@ public function testSaveWithDefaultValues() {

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

```bash
$ phpunit GeneratedObjectTest
```
$ phpunit GeneratedObjectTest


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.

## Fix checkstyle ##

You can fix checkstyle __before to create your commit__ by using the Symfony2
[php-cs-fixer][] script. You just need to install the script:

$ wget http://cs.sensiolabs.org/get/php-cs-fixer.phar

Then use it on the file you have edited:

$ php php-cs-fixer.phar fix $(git ls-files -m)

## Improve the documentation ##

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.
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. Please, try to
wrap your additions around 80 characters.

[Composer]: http://getcomposer.org/
[php-cs-fixer]: http://cs.sensiolabs.org/
[Markdown]: http://daringfireball.net/projects/markdown/
[propelorm.github.com]: https://github.com/propelorm/propelorm.github.com
[GitHub Pages]: http://pages.github.com/
[PHPUnit]: http://www.phpunit.de

0 comments on commit 815f8a0

Please sign in to comment.