Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (75 loc) · 5.92 KB

CONTRIBUTING.md

File metadata and controls

109 lines (75 loc) · 5.92 KB
Raw

Contributing to SQLGlot

SQLGLot is open source software. We value feedback and we want to make contributing to this project as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features

We develop with GitHub

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

Finding tasks to work on

When the core SQLGlot team does not plan to work on an issue, it is usually closed as "not planned". This may happen when a request is exceptionally difficult to address, or because the team deems that it shouldn't be prioritized.

These issues can be a good starting point when looking for tasks to work on. Simply filter the issue list to fetch the closed issues and then search for those marked as "not planned". If the scope of an issue is not clear or you need guidance, feel free to ask for clarifications.

Before taking on a task, consider studying the AST primer and the onboarding document.

Submitting code changes

Pull requests are the best way to propose changes to the codebase, and we actively welcome them.

Pull requests should be small and they need to follow the conventions of the project. For features that require many changes, please reach out to us on Slack before making a request, in order to share any relevant context and increase its chances of getting merged.

  1. Fork the repo and create your branch from main
  2. If you've added code with non-trivial changes, add tests
  3. If you've changed APIs, update the documentation (docstrings)
  4. Ensure the test suite & linter checks pass
  5. Issue that pull request and wait for it to be reviewed by a maintainer or contributor

Note: make sure to follow the Conventional Commits guidelines when creating a PR.

IMPORTANT: Keep PRs minimal in scope

Each pull request should focus on a single, well-defined change. Avoid bundling multiple unrelated fixes or features in one PR. This makes code review faster and more effective, increases the likelihood of acceptance, and helps maintain a clean git history.

LLM-assisted contributions

Like many open source projects, SQLGlot has recently seen a surge of pull requests that are largely generated by LLMs (ChatGPT, Claude, Cursor, Copilot, etc.) with little human review. These tools can be useful, but low-effort, AI-generated PRs can create problems for the project:

  • Descriptions are often padded with boilerplate AI slop that obscures what actually changed and why.
  • The code frequently misses subtle nuances and edge cases that the author never took the time to understand.
  • Reviewing them carefully consumes a disproportionate amount of maintainer time, often more than it would take a maintainer to implement the change correctly from scratch.

Our policy:

  • You are fully responsible for every line you submit. "An LLM wrote it" is not an acceptable answer to a review question. If you cannot explain why a change is correct, do not open the PR.
  • Disclose LLM use. Human contributors who used an LLM are encouraged to mention it in a disclaimer.
  • Write the PR description yourself. Keep it concise and human-written; a few clear sentences without emojis summaries and restatements of the diff are worth more than a wall of text.
  • If you are a new contributor, prefer opening an issue over a PR. We are interested in growing long-term contributors who genuinely understand the codebase. If you have found a bug or have a fix in mind, open a well-written issue with a reproducible example (see below). The core team can usually address it faster and more accurately than it takes to review an AI-generated PR.
  • Low-effort PRs that are mostly LLM-generated with little human input will be closed without a detailed review, with a pointer to this policy. This is not a judgment of you as a contributor, it is simply how we keep review bandwidth focused on changes that move the project forward.

Report bugs using GitHub's issues

We use GitHub issues to track public bugs. Report a bug by opening a new issue.

Great Bug Reports tend to have:

  • A quick summary and/or background
  • Steps to reproduce
    • Be specific
    • Give sample code if you can
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
  • References (e.g. documentation pages related to the issue)

Start a discussion using GitHub's discussions

We use GitHub discussions to discuss about the current state of the code. If you want to propose a new feature, this is the right place to do it. Just start a discussion, and let us know why you think this feature would be a good addition to SQLGlot (by possibly including some usage examples).

Deployment (maintainers only)

To deploy a new SQLGlot version, follow these steps:

  1. Run git pull to make sure the local git repo is at the head of the main branch
  2. Do a git tag operation to bump the SQLGlot version, e.g. git tag v28.5.0
  3. Run git push && git push --tags to deploy the new version

License

By contributing, you agree that your contributions will be licensed under its MIT License.

References

This document was adapted from briandk's template.