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.
Commit files with LF line endings. See Dealing with line endings chapter on GitHub.
Working on your patch
Before you start working on your patch, create a new branch for your changes.
$ git checkout -b new_branch_name
The branch name should be short meaningful expression such as “secured-signals” or “form-email-validation”.
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 Nette Framework repository root.
Now you should be able to run tests with
./tests/run-tests.sh in the unix-like terminal or
tests\RunTests.bat in the Windows terminal.
Some tests will probably be failing due to missing php.ini. Therefore you should call the runner with parameter -c and specify the path to php.ini, for example ./tests/run-tests.sh -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.
Commiting the changes
After you have changed the code, you have to commit your changes. Do not commit everything at all. 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 neither
- Your code does not break any tests.
- Your code change is tested.
- You are commiting all needed files, you are not commiting useless white-space changes.
- You keep code convention & coding standard used in Nette Framework. The code must
contain chars only from
\t\r\n\x20..\x7Erange, the code uses only tabs for indentation, the code does not contain white-space on the right side.
Pull-requesting the commits
If you are satisfied with your code changes & commits, you have to push you commits to your remote repository.
$ git push origin new_branch_name
Changes are present publicly, however, you have to propose your changes for integration into master branch of Nette Framework. 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.” or “Fixing form validations for UTF-8 emails”.
Pull request description should have contain some more specific information about your code changes. The description of pull-request must contain this information table about you changes:
- feature / bugfix - issues - #2, #3 - documentation - not needed / needed: nette/web-content#65 - BC break - yes / no
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 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:
- issues – #123
- documentation – needed: nette/web-content#43
- 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.