Contributing to Code
********************

.[perex]
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|https://github.com] 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|https://rogerdudler.github.io/git-guide/] and consider using one of the many [graphical clients|https://git-scm.com/downloads/guis].


Preparing the Environment and Repository
----------------------------------------

1) On GitHub, create a [fork|https://help.github.com/en/github/getting-started-with-github/fork-a-repo] of the [package repository|www:packages] that you intend to modify
2) [Clone|https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] this repository to your computer
3) Install the dependencies, including [Nette Tester|tester:], using the `composer install` command
4) Verify that the tests are working by running `composer tester`
5) Create a [new branch|#New Branch] based on the latest released version


Implementing Your Own Changes
-----------------------------

Now you can make your own code adjustments:

1) Implement the desired changes and do not forget about the tests
2) Make sure the tests run successfully using `composer tester`
3) Check if the code meets the [#coding standards]
4) Save (commit) the changes with a description in [this format|#Commit Description]

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:

1) Push the changes to GitHub to your fork
2) From there, submit them to the Nette repository by creating a [pull request|https://help.github.com/articles/creating-a-pull-request] (PR)
3) Provide [sufficient information|#pull request description] in the description


Incorporating Feedback
----------------------

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

1) Keep track of the proposed changes
2) Incorporate them as new commits or [merge them with previous ones|https://help.github.com/en/github/using-git/about-git-rebase]
3) 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|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:

```shell
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:

```shell
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:

```shell
/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 .(new feature)", "fixed .(correction)", "refactored .(code change without behavior change)", 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 -->
```


{{priority: -1}}