Skip to content

Contributor Guide

Welcome to the Opteryx Contributor Guide

We're excited you're considering contributing to Opteryx and look forward to reviewing your contribution.

Opteryx is an open source software project, we value your feedback and want to make contributing to this project as easy and transparent as possible. In this section you will find information to help you to bring your unique skills and experience and join us in building Opteryx.

Opteryx is primarily written in Python, but you don't need to be a Python developer to contribute. All contributions, bug reports, documentation improvements, and ideas are welcome.

Our Tools

GitHub

Join us on Github

We use GitHub to host the code, track feature requests, perform testing, report bugs and maintain documentation.

All submissions, including submissions by core project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Pull requests that add support for, or fix a bug in, a feature in a popular RDBMS, or address deficiency in documentation, will likely be accepted after a brief review. For more substantive changes you should start a discussion to coordinate with maintainers.

We have included a number of tests which run automatically when code is submitted to help maintain consistency and quality of the codebase, note that these may not be automatically triggered for new contributors. Pull requests which do not meet the quality criteria will not be reviewed or merged.

Code Style and Quality

For consistent style, code should follow these guidelines:

  • Imports on separate lines (imports then froms)
  • Variables should be in snake_case
  • Classes should be in PascalCase
  • Constants should be in UPPER_SNAKE_CASE
  • Methods should have docstrings
  • Black formatted
  • Self-explanatory method, class and variable names
  • Type hints, especially in function definitions

All code changes should include:

  • Corresponding unit and regression tests
  • A clean execution of the CI tests on GitHub
  • Updated documentation where relevant
  • Attributed external sources - even if there is no explicit license requirement

Comments

  • Computers will interpret anything, humans need help interpreting code
  • Spend time writing readable code rather than verbose comments
  • Humans struggle with threading, recursion, parallelization, variables called x and more than 10... of anything
  • Comments should usually be more than just the code in other words
  • Well-written code doesn't always need comments

Discord

Discord is our target channel for community and discussion.

Join us on Discord

Licensing

All code is licensed under the Apache Software License 2.0, unless clearly stated otherwise.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

Any submissions with incompatible license or license conditions may be rejected from inclusion.

🚀 Get Started Now!

We hope this guide has provided you with all the information you need to start contributing to Opteryx. Here's how you can take the next steps:

  • Star the Project: Show your support by starring the project on GitHub.
  • Fork and Clone: Fork the project and clone it to your local machine. Follow our setup guides for Debian/Ubuntu or macOS to get your environment ready.
  • Find an Issue: Browse through our open issues to find one that interests you. If you're new to the project, look for issues tagged as good first issue.
  • Join the Discussion: If you have ideas or want to collaborate, join our Discord channel and introduce yourself.
  • Submit a Pull Request: Once you're ready with your changes, create a pull request. Make sure to review the PR guidelines one last time to ensure a smooth process.
  • Spread the Word: If you find Opteryx helpful, let the community know! Blog about your experiences, tweet about it, or present it at meetups.

Remember, every contribution counts, be it code, documentation, or outreach. We're excited to have you on board!

Feel free to reach out to the maintainers if you have any questions. We're here to help!