Contributing to Code
Nette Framework uses Git and GitHub for maintaining the code base. The best way to contribute is to commit your changes to your own fork and then make a pull request on GitHub. This document summarize the major steps for successful contributing.
Working on your Patch
Before you start working on your patch, create a new branch for your changes.
git checkout -b new_branch_name
You can work on your code change.
Testing your Changes
You need to install Nette Tester. The easiest way is to call
composer install in repository root. Now you should
be able to run tests with
./vendor/bin/tester in the unix-like terminal or
vendor\bin\tester in the
Some tests may fail due to missing php.ini. Therefore you should call the runner with parameter -c and specify the path to
php.ini, for example
./vendor/bin/tester -c ./tests/php.ini.
After you are able to run the tests, you can implement your own or change the failing to match the new behavior. Read more about testing with Nette Tester in documentation page.
Your code must follow coding standard used in Nette Framework. It is easy because there is automated checker & fixer. It requires PHP 7.1 and can be installed via Composer to your chosen global directory:
composer create-project nette/coding-standard /path/to/nette-coding-standard
Now you should be able to run tool in the terminal. For example, this command checks and fixes code in folders
tests in current directory:
/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix
Commiting the Changes
After you have changed the code, you have to commit your changes. Create more commits, one for each logical step. Each commit should have been usable as is – without other commits. So, the appropriate tests should be also included in the same commit.
Please, double-check your code fits the rules:
- Code does not generate any errors
- Your code does not break any tests.
- Your code change is tested.
- You are not commiting useless white-space changes.
Commit message should follow format
Latte: fixed multi template rendering [Closes # 69] ie:
- an area followed by a colon
- the purpose of the commit in the past, if possible, start with „added.“, „fixed.“, „refactored.“, changed, removed
- eventual link to issue tracker
- if commit cancels backward compatibility, add „BC break“
- there may be one free line after the subject and a more detailed description including links to the forum.
Pull-requesting the Commits
If you are satisfied with your code changes & commits, you have to push you commits to GitHub.
git push origin new_branch_name
Changes are present publicly, however, you have to propose your changes for integration into master branch of Nette. To do that, make a pull request Each pull request has a title and a description. Please provide some describing title. It's often similar to the branch name, for example „Securing signals against CSRF attack.“
Pull request description should have contain some more specific information about your code changes:
- bug fix? yes/no <!-- #issue numbers, if any --> - new feature? yes/no - BC break? yes/no - doc PR: nette/docs#??? <!-- highly welcome, see https://nette.org/en/writing -->
Please change the information table to fit your pull request. Comments to each list item:
- Says if the pull request adds feature or it is a bugfix.
- References eventually related issue, which will be closed after merging the pull request.
- Says if the pull request needs the documentation changes, if yes, provide references to the appropriate pull requests. You don't have to provide the documentation change immediately, however, the pull request won't be merged if the documentation change is needed. The documentation change must be prepared for English documentation, other language mutations are optional.
- Says if the pull request creates a BC break. Please, consider everything which changes public interface as a BC break.
The final table could look like:
- bug fix? no - new feature? yes issue #123 - BC break? no
Reworking your Changes
It is really common to receive comments to your code change. Please, try to follow proposed changes and rework your commits to do that. You can commit proposed changes as new commits and then squash them to the previous ones. See Interactive rebase chapter on GitHub. After rebasing your changes, force-push your changes to your remote fork, everything will be automatically propagate to the pull request.