title_wip

[Edit this page](https://github.com/ClickHouse/ClickHouse/tree/master/docs/en/development/developer-instruction.md)

ClickHouse can be built on Linux, FreeBSD and macOS.
If you use Windows, you can still build ClickHouse in a virtual machine running Linux, e.g. [VirtualBox](https://www.virtualbox.org/) with Ubuntu.

## Create a Repository on GitHub[​](#create-a-repository-on-github "Direct link to Create a Repository on GitHub")

To start developing for ClickHouse you will need a [GitHub](https://www.github.com/) account.
Please also generate an SSH key locally (if you don't have one already) and upload the public key to GitHub as this is a prerequisite for contributing patches.

Next, fork the [ClickHouse repository](https://github.com/ClickHouse/ClickHouse/) in your personal account by clicking the "fork" button in the upper right corner.

To contribute changes, e.g., a fix for an issue or a feature, first commit your changes to a branch in your fork, then create a "Pull Request" with the changes to the main repository.

For working with Git repositories, please install Git. For example, in Ubuntu, run:

```
sudo apt update
sudo apt install git
```

A Git cheatsheet can be found [here](https://education.github.com/git-cheat-sheet-education.pdf).
A detailed Git manual is [here](https://git-scm.com/book/en/v2).

## Clone the repository to your development machine[​](#clone-the-repository-to-your-development-machine "Direct link to Clone the repository to your development machine")

First, download the source files to your working machine, i.e. clone the repository:

```
git clone [email protected]:your_github_username/ClickHouse.git  # replace the placeholder with your GitHub user name
cd ClickHouse
```

This command creates a directory `ClickHouse/` containing the source code, tests, and other files.
You can specify a custom directory for checkout after the URL, but it is important that this path does not contain whitespaces as this may break the build later on.

ClickHouse's Git repository uses submodules to pull in 3rd party libraries.
Submodules are not checked out by default.
You can either

- run `git clone` with option `--recurse-submodules`,
- if `git clone` is run without `--recurse-submodules`, run `git submodule update --init --jobs <N>` to checkout all submodules explicitly. (`<N>` can be set for example to `12` to parallelize the download.)
- if `git clone` is run without `--recurse-submodules` and you like to use [shallow](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) submodule checkout to omit history in submodules to save some space, run `./contrib/update-submodules.sh`. This alternative is used by CI but not recommended for local development as it makes working with submodules less convenient and slower.

To check the status of the Git submodules, run `git submodule status`.

If you get the following error message

```
Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
```

the SSH keys for connecting to GitHub are missing.
These keys are normally located in `~/.ssh`.
For SSH keys to be accepted you need to upload them in GitHub's settings.

You can also clone the repository via HTTPS:

```
git clone https://github.com/ClickHouse/ClickHouse.git
```

This, however, will not let you send your changes to the server.
You can still use it temporarily and add the SSH keys later replacing the remote address of the repository with `git remote` command.

You can also add original ClickHouse repo address to your local repository to pull updates from there:

```
git remote add upstream [email protected]:ClickHouse/ClickHouse.git
```

After successfully running this command you will be able to pull updates from the main ClickHouse repo by running `git pull upstream master`.

Tip

Please do not use verbatim `git push`, you may push to the wrong remote and/or the wrong branch.
It is better to specify the remote and branch names explicitly, e.g. `git push origin my_branch_name`.

## Writing code[​](#writing-code "Direct link to Writing code")

Below you can find some quick links which may be useful when writing code for ClickHouse:

- [ClickHouse Architecture](/docs/development/architecture).
- [Code style guide](/docs/development/style).
- [Third-party libraries](/docs/development/contrib#adding-and-maintaining-third-party-libraries)
- [Writing tests](/docs/development/tests)
- [Open issues](https://github.com/ClickHouse/ClickHouse/issues?q=is%3Aopen+is%3Aissue+label%3A%22easy+task%22)

### IDE[​](#ide "Direct link to IDE")

[Visual Studio Code](https://code.visualstudio.com/) and [Neovim](https://neovim.io/) are two options that have worked well in the past for developing ClickHouse. If you are using VS Code, we recommend using the [clangd extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) to replace IntelliSense as it is much more performant.

[CLion](https://www.jetbrains.com/clion/) is another great alternative. However, it can be slower on larger projects like ClickHouse. A few things to keep in mind when using CLion:

- CLion creates a `build` path on its own and automatically selects `debug` for the build type
- It uses a version of CMake that is defined in CLion and not the one installed by you
- CLion will use `make` to run build tasks instead of `ninja` (this is normal behavior)

Other IDEs you can use are [Sublime Text](https://www.sublimetext.com/), [Qt Creator](https://www.qt.io/product/development-tools), or [Kate](https://kate-editor.org/).

## Create a pull request[​](#create-a-pull-request "Direct link to Create a pull request")

Navigate to your fork repository in GitHub's UI.
If you have been developing in a branch, you need to select that branch.
There will be a "Pull request" button located on the screen.
In essence, this means "create a request for accepting my changes into the main repository".

A pull request can be created even if the work is not completed yet.
In this case please put the word "WIP" (work in progress) at the beginning of the title, it can be changed later.
This is useful for cooperative reviewing and discussion of changes as well as for running all of the available tests.
It is important that you provide a brief description of your changes, it will later be used for generating release changelog.

Testing will commence as soon as ClickHouse employees label your PR with a tag "can be tested".
The results of some first checks (e.g. code style) will come in within several minutes.
Build check results will arrive within half an hour.
The main set of tests will report itself within an hour.

The system will prepare ClickHouse binary builds for your pull request individually.
To retrieve these builds click the "Details" link next to "Builds" entry in the list of checks.
There you will find direct links to the built .deb packages of ClickHouse which you can deploy even on your production servers (if you have no fear).

## Write documentation[​](#write-documentation "Direct link to Write documentation")

Every pull request which adds a new feature must come with proper documentation.
If you'd like to preview your documentation changes the instructions for how to build the documentation page locally are available in the README.md file [here](https://github.com/ClickHouse/clickhouse-docs).
When adding a new function to ClickHouse you can use the template below as a guide:

```
# newFunctionName

A short description of the function goes here. It should describe briefly what it does and a typical usage case.

**Syntax**

\```sql
newFunctionName(arg1, arg2[, arg3])
\```

**Arguments**

- `arg1` — Description of the argument. [DataType](../data-types/float.md)
- `arg2` — Description of the argument. [DataType](../data-types/float.md)
- `arg3` — Description of optional argument (optional). [DataType](../data-types/float.md)

**Implementation Details**

A description of implementation details if relevant.

**Returned value**

- Returns {insert what the function returns here}. [DataType](../data-types/float.md)