# Contributing to OpenTTD

Looking to contribute something to OpenTTD? **Here's how you can help.**

Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project.

In return, they should reciprocate that respect in addressing your issue or assessing patches and features.

## Using the issue tracker

The [issue tracker](https://github.com/OpenTTD/OpenTTD/issues) is the preferred channel for [bug reports](#bug-reports), but please respect the following restrictions:

* Please **do not** use the issue tracker for help playing or using OpenTTD.

* Please **do not** derail or troll issues. Keep the discussion on topic and respect the opinions of others.

* Please **do not** post comments consisting solely of "+1" or ":thumbsup:".

Use [GitHub's "reactions" feature](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments) instead.

We reserve the right to delete comments which violate this rule.

* Please **do not** open issues or pull requests regarding add-on content in NewGRF, GameScripts, AIs, etc.

* Please use [the web translator](https://translator.openttd.org/) to submit corrections and improvements to translations of the game.

## Bug reports

A bug is a _demonstrable problem_ that is caused by the code in the repository.

Good bug reports are extremely helpful, so thanks!

Guidelines for bug reports:

0. Please don't report issues with games where you changed NewGRFs mid-game. (This can be verified with the `gamelog` console command in-game.)

1. Please don't report issues with modified versions of OpenTTD (patchpacks, unofficial ports, and similar).

2. **Use the GitHub issue search** — check if the issue has already been

reported.

3. **Check if the issue has been fixed** — try to reproduce it using the latest `nightly` build of OpenTTD, available from https://www.openttd.org

4. **Isolate the problem** — ideally create reproducible steps with an attached savegame and screenshots. Try to use few or no NewGRFs, AIs etc if possible.

A good bug report shouldn't leave others needing to chase you up for more information.

Please try to be as detailed as possible in your report.

This means don't request for a solution, but describe the problem you see and how/why you think it should be fixed.

For feature request we have a strict policy.

Keeping issues around with "a good idea" or "not really a bug but we should maybe fix it" turns out to have the reversed effect: nobody looks at it anymore.

Although we really appreciate feedback and ideas, we will close feature requests that we don't expect to fulfill in the next year.

Many of those ideas etc do have a place on the [forums](https://www.tt-forums.net); and if enough people like it, someone will stand up and make it.

It's usually best to discuss on [Discord](https://discord.gg/openttd) before opening a feature request or working on a large feature in a fork.

Discussion can take time, but it can be productive and avoid disappointment. :)

## Pull requests

Good pull requests—patches, improvements, new features—are a fantastic help.

Pull requests should fit with the [goals of the project](./CONTRIBUTING.md#project-goals).

**Please do ask first** before embarking on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

Every pull request should have a clear scope, with no unrelated commits.

Adhering to the following process is the best way to get your work included in the project:

1. [Fork](https://help.github.com/fork-a-repo/) the project, clone your fork, and configure the remotes:

```bash

git clone https://github.com/<your-username>/OpenTTD.git openttd

git clone https://github.com/OpenTTD/OpenTTD-git-hooks.git openttd_hooks

cd openttd

git remote add upstream https://github.com/OpenTTD/OpenTTD.git

cd .git/hooks

ln -s ../../../openttd_hooks/hooks/* .

```

2. If you cloned a while ago, get the latest changes from upstream:

```bash

git fetch upstream

```

3. Create a new topic branch (off the main project development branch) to

contain your feature, change, or fix:

```bash

git checkout upstream/master -b <topic-branch-name>

```

Use Git's [interactive rebase](https://docs.github.com/en/get-started/using-git/about-git-rebase) feature to tidy up your commits before making them public.

5. Locally rebase the upstream development branch into your topic branch:

```bash

git fetch upstream

git rebase upstream/master

```

6. Push your topic branch up to your fork the first time:

```bash

git push --set-upstream origin <topic-branch-name>

```

And any time after that:

```bash

git push

```

7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title and description against the `master` branch.

**IMPORTANT**: By submitting a pull request or patch, you agree to the [License](#license) and the [Privacy Notice](CONTRIBUTING.md#privacy-notice).

### Pull request validation

Continuous integration (CI) tools monitor pull requests, and help us identify build and code quality issues.

The results of the CI tests will show on your pull request.

By clicking on Details you can further zoom in; in case of a failure it will show you why it failed.

In case of success it will report how awesome you were.

### Are there any development docs?

There is no single source for OpenTTD development docs. It's a complex project with a long history, and multiple APIs.

A good entry point is [Development](https://wiki.openttd.org/en/Development/) on the OpenTTD wiki; this provides links to wiki documentation and other sources.

The GitHub repo also includes some non-comprehensive documentation in [/docs](./docs).

You may also want the guide to [compiling OpenTTD](./COMPILING.md).

## Project goals

### What are the goals of the official branch?

The main goals of the official branch are:

- Stay faithful to the original gameplay from Transport Tycoon Deluxe

- Improve the user interface

- Allow extending the gameplay with add-ons / mods via supported content APIs

- Provide a (relatively) stable core for both players of the official branch, and for authors of add-ons and maintainers of patchpacks