Git workflow for Codeception contributors

This guide was inspired by Yii framework well-written guide for contributors.

1. Fork the Codeception repository on github and clone your fork to your development environment

git clone git@github.com:YOUR-GITHUB-USERNAME/Codeception.git

If you have trouble setting up GIT with GitHub in Linux, or are getting errors like "Permission Denied (publickey)", then you must setup your GIT installation to work with GitHub

2. Add the main Codeception repository as an additional git remote called "upstream"

Change to the directory where you cloned Codeception, normally, "Codeception". Then enter the following command:

git remote add upstream git@github.com:Codeception/Codeception.git

3. Make sure there is an issue created for the thing you are working on.

All new features and bug fixes should have an associated issue to provide a single point of reference for discussion and documentation. Take a few minutes to look through the existing issue list for one that matches the contribution you intend to make. If you find one already on the issue list, then please leave a comment on that issue indicating you intend to work on that item. If you do not find an existing issue matching what you intend to work on, please open a new issue for your item. This will allow the team to review your suggestion, and provide appropriate feedback along the way.

For small changes or documentation issues, you don't need to create an issue, a pull request is enough in this case.

4. Pull the latest code from the main Codeception branch

If you already have cloned repo from your github account, then dont forget to pull latest changes from main Codeception repo.

git pull upstream

You should start at this point for every new contribution to make sure you are working on the latest code.

5. Create a new branch for your feature based on the current Codeception master branch

Each separate bug fix or change should go in its own branch. For example:

git checkout -b name-of-your-branch-goes-here

6. Write code for fixing issue or enh.

Also if you are familiar with phpunit tests, you can write them and run to be sure that your code works as needed. To run any Codeception tests from folder Codeception/tests you first need to install all composer dependences through Composer, so do this in Codeception directory:

php composer.phar install

To run your unit-tests you can do this:

php codecept run unit

To run specific unit-test, for example "Codeception\ConfigurationTest.php" do this

php codecept run unit Codeception\ConfigurationTest.php

Other tests can be executed in same way.

7. Commit your changes

add the files/changes you want to commit to the staging area with

git add path/to/my/file.php

You can use the -p option to select the changes you want to have in your commit.

9. Open a pull request against upstream.

Go to your repository on github and click "Pull Request", choose your branch on the right and enter some more details in the comment box.

Note that each pull-request should fix a single change.

Important: Make sure that your pull request is based on the correct branch in Codeception. It should match the branch on which your fix is based. GitHub by default generates a pull request against the default branch of the target repository, regardless of which branch you based your correction on. If it doesn't match then you will need to edit the request and change the base branch.