Proposing a Change in 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.

Preparing Environment

Start with forking Nette on GitHub. Carefully set up your local Git environment, configure your username and email, these credentials will identify your changes in Nette Framework history.

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.

If possible, make changes from the last released version.

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

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.

Coding Standards

Your code must follow coding standard used in Nette Framework. It is easy because there is automated checker & fixer. It 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 src and tests in current directory:

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Committing 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 committing 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.