## File: README.md

## Development

See [DEVELOPMENT](.github/DEVELOPMENT.md) for information about development and release process,
code style and guidelines for implementors of Trino plugins.

See [CONTRIBUTING](.github/CONTRIBUTING.md) for contribution requirements.

## Security

See the project [security policy](.github/SECURITY.md) for
information about reporting vulnerabilities.

Trino supports [reproducible builds](https://reproducible-builds.org) as of version 449.

## Build requirements

* Mac OS X or Linux
  * Note that some npm packages used to build the web UI are only available
    for x86 architectures, so if you're building on Apple Silicon, you need
    to have Rosetta 2 installed.
* Java 25.0.1+, 64-bit
* Docker
  * Turn SELinux or other systems disabling write access to the local checkout
    off, to allow containers to mount parts of the Trino source tree

## Building Trino

Trino is a standard Maven project. Simply run the following command from the
project root directory:

    ./mvnw clean install -DskipTests

On the first build, Maven downloads all the dependencies from the internet
and caches them in the local repository (`~/.m2/repository`), which can take a
while, depending on your connection speed. Subsequent builds are faster.

Trino has a comprehensive set of tests that take a considerable amount of time
to run, and are thus disabled by the above command. These tests are run by the
CI system when you submit a pull request. We recommend only running tests
locally for the areas of code that you change.

## Running Trino in your IDE

### Overview

After building Trino for the first time, you can load the project into your IDE
and run the server.  We recommend using
[IntelliJ IDEA](http://www.jetbrains.com/idea/). Because Trino is a standard
Maven project, you can easily import it into your IDE. In IntelliJ, choose
*Open Project* from the *Quick Start* box or choose *Open*
from the *File* menu and select the root `pom.xml` file.

After opening the project in IntelliJ, double-check that the Java SDK is
properly configured for the project:

* Open the File menu and select Project Structure
* In the SDKs section, ensure that JDK 25 is selected (create one if none exist)
* In the Project section, ensure the Project language level is set to 25

### Running a testing server

The simplest way to run Trino for development is to run the `TpchQueryRunner`
class. It will start a development version of the server that is configured with
the TPCH connector. You can then use the CLI to execute queries against this
server. Many other connectors have their own `*QueryRunner` class that you can
use when working on a specific connector. The VM option generally required here
is `--add-modules jdk.incubator.vector`, but various `*QueryRunner` classes
might require additional options (if necessary, check the `air.test.jvm.additional-arguments`
property in the `pom.xml` file of the module from which the runner comes).

### Running tests from the IDE

When running individual test classes directly from IntelliJ, you need to
configure the JUnit run configuration template. Go to Run/Debug Configurations >
Edit Configuration Templates > JUnit > VM options and set the value to
`-ea --add-modules=jdk.incubator.vector`. Some tests may rely on JVM options provided
by airbase (e.g. `-XX:-OmitStackTraceInFastThrow`), so check for that too.

### Running the full server

Trino comes with sample configuration that should work out-of-the-box for
development. Use the following options to create a run configuration:

* Main Class: `io.trino.server.DevelopmentServer`
* VM Options: `-ea -Dconfig=etc/config.properties -Dlog.levels-file=etc/log.properties -Djdk.attach.allowAttachSelf=true --sun-misc-unsafe-memory-access=allow --add-modules jdk.incubator.vector`
* Working directory: `$MODULE_DIR$`
* Use classpath of module: `trino-server-dev`

The working directory should be the `trino-server-dev` subdirectory. In
IntelliJ, using `$MODULE_DIR$` accomplishes this automatically.

If `VM options` doesn't exist in the dialog, you need to select `Modify options`
and enable `Add VM options`.

To adjust which plugins are enabled for the development server, adjust the value of
`plugin.bundles` in `config.properties`. Each entry in this list must represent a plugin
specified by one of the following options:
* A path to a `pom.xml` or `*.pom` file describing a Maven project that produces a plugin.
* Maven coordinates, in the form `<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>`. The plugin will be loaded via Maven and therefore must be available in your local repository or a remote repository.
* A path to a plugin directory containing JAR files. See [Deploying a custom plugin](https://trino.io/docs/current/develop/spi-overview.html#deploying-a-custom-plugin) for more details.

If you want to use a plugin in a catalog, you must add a corresponding
`<catalog_name>.properties` file to `testing/trino-server-dev/etc/catalog`.

### Running the CLI

Start the CLI to connect to the server and run SQL queries:

    client/trino-cli/target/trino-cli-*-executable.jar

Run a query to see the nodes in the cluster:

    SELECT * FROM system.runtime.nodes;

Run a query against the TPCH connector:

    SELECT * FROM tpch.tiny.region;

---

## File: docs/README.md

# Trino documentation

The `docs` module contains the reference documentation for Trino.

- [Writing and contributing](#writing-and-contributing)
- [Tools](#tools)
- [Fast doc build option](#fast-doc-build-option)
- [Default build](#default-build)
- [Viewing documentation](#viewing-documentation)
- [Versioning](#versioning)
- [Style check](#style-check)
- [Contribution requirements](#contribution-requirements)
- [Workflow](#workflow)
- [Videos](#videos)
- [Docker container](#docker-container)

## Writing and contributing

We welcome any contributions to the documentation. Contributions must [follow
the same process as code contributions](https://trino.io/development/) and
can be part of your code contributions or separate documentation improvements.

The documentation follows the Google developer documentation style guide for any
new documentation:

- [Google developer documentation style guide](https://developers.google.com/style)
- [Highlights](https://developers.google.com/style/highlights)
- [Word list](https://developers.google.com/style/word-list)
- [Style and tone](https://developers.google.com/style/tone)
- [Writing for a global audience](https://developers.google.com/style/translation)
- [Cross-references](https://developers.google.com/style/cross-references)
- [Present tense](https://developers.google.com/style/tense)

The Google guidelines include more material than listed here, and are used as a
guide that enables easy decision-making about proposed doc changes. Changes to
existing documentation to follow these guidelines are underway.

As a specific style note, because different readers may perceive the phrases "a
SQL" or "an SQL" to be incorrect depending on how they pronounce SQL, aim to
avoid use of "a/an SQL" in Trino documentation. Try to reword, re-order, or
adjust writing so that it is not necessary. If there is absolutely no way around
it, default to using "a SQL."

Other useful resources:

- [Style check](#style-check)
- [Google Technical Writing Courses](https://developers.google.com/tech-writing)
- [Myst guide](https://mystmd.org/guide)

## Tools

Documentation source files can be found in [Myst Markdown](https://mystmd.org/)
(`.md`) format in `src/main/sphinx` and subdirectories. Refer to the [Myst
guide](https://mystmd.org/guide) and the existing documentation for more
information about how to write and format the documentation source.

The engine used to create the documentation in HTML format is the Python-based
[Sphinx](https://www.sphinx-doc.org).

The [fast doc build option](#fast-doc-build-option) requires *only* a local
installation of [Docker Desktop on
Mac](https://docs.docker.com/docker-for-mac/install/) or [Docker Engine on
Linux](https://docs.docker.com/engine/install/). No other tools are required.

The default formal build of the docs is performed with Apache Maven, which requires an
installation of a Java Development Kit.

## Fast doc build option

For fast local build times when writing documentation, you can run the Sphinx
build directly. The build runs inside a Docker container and thus does not
require having anything installed locally other than Docker. You can run the
Sphinx build on a fresh clone of the project, with no prerequisite commands. For
example:

```bash
docs/build
```

Sphinx attempts to perform an incremental build, but this does not work
in all cases, such as after editing the CSS. You can force a full rebuild
by removing the ``target/html`` directory:

```bash
rm -rf docs/target/html
```

## Default build

The default build uses Apache Maven and Java as does the rest of the
Trino build. You only need to have built the current Trino version from the root.
That is, before building the docs the first time, run the following command:

```bash
./mvnw clean install -DskipTests
```

Subsequently, you can build the doc site using the Maven wrapper script:

```bash
./mvnw -pl docs clean install
```

If you have Maven installed and available on the path, you can use the `mvn` command
directly.

This also performs other checks, and is the authoritative way to build the
docs. However, using Maven is also somewhat slower than using Sphinx directly.

## Viewing documentation

However you build the docs, the generated HTML files can be found in the folder
`docs/target/html/`.

You can open the file `docs/target/html/index.html` in a web browser on
macOS with

```bash
open docs/target/html/index.html
```

or on Linux with

```bash
xdg-open docs/target/html/index.html
```

Or you can directly call your browser of choice with the same filename. For example, on Ubuntu
with Chromium:

```bash
chromium-browser docs/target/html/index.html
```

Alternatively, you can start a web server with that folder as root, such as with
the following Python command. You can then open
[http://localhost:4000](http://localhost:4000) in a web browser.

```bash
cd docs/target/html/
python3 -m http.server 4000
```

In order to see any changes from the source files in the HTML output, simply
re-run the ``build`` command and refresh the browser.

## Versioning

The version displayed in the resulting HTML is read by default from the top-level Maven
`pom.xml` file's `version` field.

To deploy a specific documentation set (such as a SNAPSHOT version) as the release
version you must override the pom version with the `TRINO_VERSION`
environment variable.

```bash
TRINO_VERSION=355 docs/build
```

If you work on the docs across multiple builds, you can export the
variable and use it with Sphinx.

```bash
export TRINO_VERSION=354
docs/build
```

This is especially useful when deploying doc patches for a release where the
Maven pom has already moved to the next SNAPSHOT version.

## Style check

The project contains a configuration for [Vale](https://vale.sh) and the
Google developer documentation style. Vale is a command-line tool to check for
editorial style issues of a document or a set of documents.

Install Vale with Homebrew on macOS or follow the instructions on the website.

```
brew install vale
```

The `docs` folder contains the necessary configuration to use vale for any
document in the repository:

* `.vale` directory with Google style setup
* `.vale/config/vocabularies/Base/accept.txt` file for additional approved
  words and spelling
* `.vale.ini` configuration file configured for Markdown and reStructuredText
  files

With this setup you can validate an individual file from the repository root by
specifying the path:

```
vale docs/src/main/sphinx/overview/use-cases.md
```

You can also use directory paths and all files within.

Treat all output from Vale as another aid for improving the docs. Fixing any
issues is not required, but it can help you learn more about the [Google style
guide](https://developers.google.com/style) that we try to follow.

## Contribution requirements


Contributing corrections or new explanations to the Trino documentation
requires only a willingness to help and submission of your [Contributor
License Agreement](https://github.com/trinodb/cla) (CLA).

## Workflow

The procedure to add a documentation contribution is the same as for [a code
contribution](https://trino.io/development/process.html).

* In the Trino project's [GitHub Issues
  list](https://github.com/trinodb/trino/issues), identify documentation issues
  by filtering on the [``docs``
  label](https://github.com/trinodb/trino/issues?q=is%3Aissue+is%3Aopen+label%3Adocs).

* If you want to help Trino documentation, but don't know where to start, look
  in the Issues list for both the [``docs`` and ``good first issue``
  labels](https://github.com/trinodb/trino/issues?q=is%3Aissue+is%3Aopen+label%3Adocs+label%3A%22good+first+issue%22).

* If the doc fix you have in mind does not yet have an issue, add one (which
  requires a signed CLA). Add the ``docs`` label to your new issue.

* You can discuss proposed doc changes in the #docs channel of the [Trino
  Slack](https://trino.io/slack.html).

* For a larger contribution, create a GitHub pull request as described
  in [GitHub
  documentation](https://docs.github.com/en/github/getting-started-with-github).
  In brief, this means:

  * [Create a fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of the
    [trinodb/trino](https://github.com/trinodb/trino) repository.

  * Create a working branch in your fork.

  * Make your edits in your working branch and push them to your fork.

  * In a browser, open your fork in GitHub, which offers to submit a pull
    request for you.

## Videos

1. See [**Contributing to the Trino
   documentation**](https://www.youtube.com/watch?v=yseFM3ZI2ro) for a
   five-minute video introduction. Note that this video uses the old RST source
   format.

2. You might select a GitHub doc issue to work on that requires you to verify
   how Trino handles a situation, such as [adding
   documentation](https://github.com/trinodb/trino/issues/7660) for SQL
   functions.

   In this case, the five-minute video [Learning Trino SQL with
   Docker](https://www.youtube.com/watch?v=y58sb9bW2mA) gives you a starting
   point for setting up a test system on your laptop.

## Docker container

The build of the docs uses a Docker container that includes Sphinx and the
required libraries. The container is referenced in the `SPHINX_IMAGE` variable
in the `build` script.

The specific details for the container are available in `Dockerfile`, and
`requirements.in`. The file `requirements.txt` must be updated after any changes
to `requirements.in`.

The container must be published to the GitHub container registry at ghcr.io with
the necessary access credentials and the following command, after modification
of the version tag `xxx` to the new desired value as used in the `build` script:

```
docker buildx build docs --platform=linux/arm64,linux/amd64 --tag ghcr.io/trinodb/build/sphinx:xxx --provenance=false --push
```

Note that the version must be updated and the command automatically also
publishes the container with support for arm64 and amd64 processors. This is
necessary so the build performs well on both hardware platforms.

After the container is published, you can update the `build` script and merge
the related pull request.

Example PRs:

* https://github.com/trinodb/trino/pull/17778
* https://github.com/trinodb/trino/pull/13225