The Trino project succeeds with your help and contributions. Find details on how
to contribute, how maintainers assist, and more related information in the
following sections:
Contribution process #
This is the process we suggest for contributions. This process is designed to
reduce the burden on project reviewers, impact on other contributors, and to
keep the amount of rework from the contributor to a minimum.
-
Sign the contributor license agreement, and
proceed with the next steps while the CLA is processed.
-
Start a discussion by creating a GitHub
issue, or asking on Slack
(unless the change is trivial, for example a spelling fix in the
documentation).
- This step helps you identify possible collaborators and reviewers.
- Does the change align with technical vision and project values?
- Will the change conflict with another change in progress? If so, work
with others to minimize impact.
- Is this change large? If so, work with others to break into smaller
steps.
-
Implement the change
- Create or update your own fork of the repository
from the Trino project that you want to
contribute to.
- If the change is large, post a draft GitHub
pull request with the title prefixed
with
[WIP]
, and share with collaborators.
- Include tests and documentation as necessary.
-
Create a GitHub pull request (PR).
- If you already have a
[WIP]
or draft PR, change it to ready for review.
- Refer to the GitHub documentation for more details about collaborating with PRs.
- Make sure the pull request passes the tests in CI.
- If known, request a review from an expert in the area changed. If
unknown, ask for help on Slack.
There are some tests that use external services, like Google BigQuery, and
require additional credentials. The Trino project cannot share these
credentials with contributors, so it runs these tests in its CI workflows
only on branches in the Trino repository, not in contributor forks.
Maintainers trigger these test runs for other pull requests as part of their
review.
-
Review is performed by one or more reviewers.
- This normally happens within a few days, but may take longer if the
change is large, complex, or if a critical reviewer is unavailable. (feel
free to ping the reviewer or DevRel team
on the pull request).
-
Address concerns and update the pull request.
- Comments are addressed to each individual commit in the pull request, and
changes should be addressed in a new
fixup!
commit
placed after each commit. This is to make it easier for the reviewer to
see what was updated.
- After pushing the changes, add a comment to the pull-request, mentioning
the reviewers by name, stating that the review comments have been
addressed. This is the only way that a reviewer is notified that you are
ready for the code to be reviewed again.
- Go to step 5.
-
Maintainer merges the pull request after final changes are accepted.
-
Maintainers organize a release to ship the next Trino version with your
improvements.
- All maintainers and the DevRel team collaborate to include your change in
the release notes.
- Roughly every week, the maintainers initiate a new release build. Exact
timing depends on any release blocker issues and availability to run the
release build.
- After the release all binaries are available and the documentation and the
website are updated.
- Finally the release is announced.
Maintainer processes #
Maintainers support the contributions from the
community and other maintainers by participating in the contribution process.
The following additional processes and steps apply for their work.
Pull request review #
The following aspects apply for reviewing pull requests.
- Code and tests should be part of the pull requests and review.
- Commit content, sequencing, and messages must be reviewed.
- Documentation should be part of the PR or available in a separate PR, that is
ideally merged and managed together with the code contribution.
-
Maintainers can schedule additional workflow runs with tests that use external
services when reviewing a PR by adding a comment:
/test-with-secrets sha=<all-40-characters>
The SHA value should be the full 40 character git SHA of a commit of the
feature branch, usually the head commit. This allows runs with the full test
suite, including third party integrations and infrastructure for branches that
are not in the core repository. Maintainers must review the pull request to
understand and assess the security implications of running the test suite on
the external service and ensure that no malicious code is run.
Pull request review and merge #
The following criteria and aspects apply for merging pull requests.
- CLA check must pass to confirm that a CLA was submitted and filed.
- CI test suite must pass, or significant evidence must be available that
failures are unrelated. This can include local test runs by the maintainer.
- Approval of a reviewing maintainer is required before a pull request can be
merged. If a maintainer authors a pull request, another maintainer must
approve it.
- Approvals and input from other reviewers are helpful for the decision of the
maintainers, but not required.
- In the event that the maintainer team is divided on whether a particular
contribution should be merged, the final decision is made by the
BDFLs of the project.
- By default, merging should be done as a Rebase and merge. Maintainers can
also use Squash and merge at their discretion. This is suitable for small
fixes on commit messages, or if PR is ready but the contributor is
unresponsive. When using squash and merge, ensure to remove the PR number that
is automatically inserted by the GitHub interface as part of the suggested new
commit message.
- The merging maintainer must assist the release team with release notes entries
creation and any necessary clarification. If necessary, the merging maintainer
collaborates with the contributors and reviewers on details.
CLA management #
Reviews and assistance for the contributor on a pull request can proceed as soon
as a PR is filed and set as ready for review. A signed CLA is required for
merging a PR. Submitted CLAs are managed by the BDFLs.
Maintainers can trigger a CLA verification on a PR by adding a comment with the
command @cla-bot check
.