Contributing to Typelevel Projects

These guidelines apply when contributing to any Typelevel organization project. Please also refer to individual project guidelines for additional guidelines.

Typelevel affiliate projects are also welcome to integrate these guidelines into their contributing guidelines.

This document focuses on policy. See also the Start Contributing guide if you want step-by-step guidance on contributing to Typelevel projects.

Welcome to the Contributing to Typelevel Projects guide. This document provides an overview of Typelevel's expectations when contributing to organization projects. At a very high level:

We want contributors who are interested in gaining a deeper understanding of the projects they're working on, learning how and why they were built, and working with the community to improve our projects.

We do not want contributors that increase the workload for maintainers without any gain for the project or any learning for the contributor.

The following sections provide guidance on how to make contributions that fall into the first category.

Respect our Code of Conduct

When you contribute to Typelevel, we expect that you respect our Code of Conduct.

Start With an Issue

To contribute to a Typelevel project, start a conversation before creating a pull request. This can be in a new issue, continuing the conversation in an existing issue, or any other communication channel being used by the project. This gives maintainers and other contributors a chance to work with you on your idea at an earlier stage to make sure it is an acceptable contribution.

When you are reporting a bug, your issue should clearly state the expected versus actual behavior you are observing. An ideal bug report includes a minimal reproducer that can easily be run (e.g. a scala-cli script, a small repository, or a saved Scastie) to demonstrate the issue. When you are unable to do so, please provide what other information you can, for example: specific steps that caused the issue, stack traces, or error messages.

When you are reporting a security issue, do not open a Github issue. See the project security policy or the Typelevel security policy.

Pull Requests

The following guidelines are particularly relevant for pull requests:

You must be mindful of the copyright and patent rights of anything you submit.

If you authored every part of your contribution and own the rights, this is not a problem. You can submit your contribution without reading further.

However, any code or assets you took from somewhere else, including code generated by AI, may be subject to copyright or patent rights, which you must respect. In such cases, you need to check the license of the material.

"Source-available" is not "open-source", and not all open-source licenses are compatible with each other. We strongly recommend against reading any "source-available" or incompatibly-licensed code before contributing to Typelevel projects.

Contribute One Change at a Time

Each pull request should contain a single self-contained change. Avoid pushing multiple unrelated changes in the same pull request.

As a rule of thumb, if your pull request could be split into two pull requests without breaking anything, it should probably be two separate pull requests.

The exception to this rule is "batching changes", where you make the same kind of change to multiple places in the codebase. In this case, it is preferable to make one larger pull request instead of many small ones.

Note: Imagine yourself in the shoes of the reviewer: how can you make the PR easy to review and approve?

This is best achieved if your pull request is simple, coherent, and uncontroversial.

Limiting pull requests to one change at a time also simplifies the Git history, makes it possible to revert or cherry-pick specific changes, and reduces the potential of accidentally introducing bugs.

Explain Your Contributions

When submitting a pull request, please make use of the pull request description.

Your pull request description should, as clearly and succinctly as possible, in your own words, explain all the necessary information to understand the changes you made.

For example, if you're just fixing a typo, a single sentence description is appropriate. However, if your change is large, we expect you to be more thorough with your explanation.

Here are the components of a thorough pull request description:

Note: You may not need every one of these components, and you do not need to copy this exact structure. Always ask yourself what would be most helpful for reviewers, and try to balance brevity and thoroughness appropriately.

Contribute Only What You Stand Behind

Only submit code that you understand, are prepared to explain to a maintainer, and be responsible for. This especially applies if you implement the idea of another person, copy code from elsewhere, or if you use AI tools to assist you with your contribution. In all of these cases, you must disclose which part of your submission wasn't fully authored by you. Regardless of the code's origin, by opening a pull request, you are putting your reputation as a contributor behind the code.

Use of AI Tools

You may use AI tools to help write code, but must write issue and pull request descriptions, documentation, code comments and other explanatory text in your own words. You are expected to understand the code you contribute well enough to write about the code yourself, regardless of how it was created.

Use of Translation Tools

While Typelevel communications are primarily conducted in English, our contributors and users are worldwide and may not be proficient in written English. Using machine translation tools (including LLM translation tools) to translate your writing to English is always acceptable. You may also include the original text in your message.

This document is based on the Godot Pull request rules and guidelines by the Godot Engine Contributors which is licensed under the CC BY 3.0 license.