Contributing to Code

Are you planning to contribute to the Nette Framework and need to familiarize yourself with the rules and procedures? This beginner's guide will walk you through the steps to effectively contribute to the code, work with repositories, and implement changes.

Procedure

To contribute to the code, it is essential to have an account on GitHub and be familiar with the basics of working with the Git version control system. If you are not familiar with Git, you can check out the git – the simple guide and consider using one of the many graphical clients.

Preparing the Environment and Repository

On GitHub, create a fork of the package repository that you intend to modify
Clone this repository to your computer
Install the dependencies, including Nette Tester, using the composer install command
Verify that the tests are working by running composer tester
Create a new branch based on the latest released version

Implementing Your Own Changes

Now you can make your own code adjustments:

Implement the desired changes and do not forget about the tests
Make sure the tests run successfully using composer tester
Check if the code meets the coding standards
Save (commit) the changes with a description in this format

You can create multiple commits, one for each logical step. Each commit should be meaningful on its own.

Submitting Changes

Once you are satisfied with the changes, you can submit them:

Push the changes to GitHub to your fork
From there, submit them to the Nette repository by creating a pull request (PR)
Provide sufficient information in the description

Incorporating Feedback

Your commits are now visible to others. It is common to receive comments with suggestions:

Keep track of the proposed changes
Incorporate them as new commits or merge them with previous ones
Resubmit the commits to GitHub, and they will automatically appear in the pull request

Never create a new pull request to modify an existing one.

Documentation

If you have changed functionality or added a new one, don't forget to add it to the documentation as well.

New Branch

If possible, make changes against the latest released version, i.e., the last tag in the branch. For the tag v3.2.1, create a branch using this command:

git checkout -b new_branch_name v3.2.1

Coding Standards

Your code must meet the coding standard used in the Nette Framework. There is an automatic tool available for checking and fixing the code. You can install it globally through Composer to a folder of your choice:

composer create-project nette/coding-standard /path/to/nette-coding-standard

Now you should be able to run the tool in the terminal. The first command checks and the second one fixes the code in the src and tests folders in the current directory:

/path/to/nette-coding-standard/ecs check
/path/to/nette-coding-standard/ecs check --fix

Commit Description

In Nette, commit subjects have the following format: Presenter: fixed AJAX detection [Closes #69]

area followed by a colon
purpose of the commit in the past tense; if possible, start with words like: added, fixed, refactored, changed, removed
if the commit breaks backward compatibility, add “BC break”
any connection to the issue tracker, such as (#123) or [Closes #69]
after the subject, there can be one blank line followed by a more detailed description, including, for example, links to the forum

Pull Request Description

When creating a pull request, the GitHub interface will allow you to enter a title and description. Provide a concise title and include as much information as possible in the description about the reasons for your change.

Also, specify in the header whether it is a new feature or a bug fix and whether it may cause backward compatibility issues (BC break). If there is a related issue, link to it so that it will be closed upon approval of the pull request.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->