Skip to content

Latest commit

 

History

History
131 lines (78 loc) · 6.2 KB

CONTRIBUTING.rst

File metadata and controls

131 lines (78 loc) · 6.2 KB

Contributing Guidelines

We love getting feedback from our users. Bugs and code contributions are great forms of feedback and we thank you for any bugs you report or code you contribute.

Reporting Issues

Before reporting a new bug, please check first to see if a similar bug already exists.

Bug reports should be as complete as possible. Please try and include the following:

  • Complete steps to reproduce the issue.
  • Any information about platform and environment that could be specific to the bug.
  • Specific version of the product you are using.
  • Specific version of the server being used.
  • Sample code to help reproduce the issue if possible.

Contributing Code

Contributing to this project is easy. You just need to follow these steps.

  • Make sure you have a user account at bugs.mysql.com. You will need to reference this user account when you submit your Oracle Contributor Agreement (OCA).
  • Sign the Oracle Contributor Agreement. You can find instructions for doing that at the OCA Page.
  • Develop your pull request. Make sure you are aware of the requirements for the project.
  • Validate your pull request by including tests that sufficiently cover the functionality you are adding.
  • Verify that the entire test suite passes with your code applied.
  • Submit your pull request. While you can submit the pull request via GitHub, you can also submit it directly via bugs.mysql.com.

Thanks again for your wish to contribute to MySQL. We truly believe in the principles of open source development and appreciate any contributions to our projects.

Setting Up a Development Environment

The following tips provide all the technical directions you should follow when writing code and before actually submitting your contribution.

  1. Make sure you have the necessary prerequisites for building the project and Pylint for static code analysis

  2. Clone MySQL Connector/Python

    shell> git clone https://github.com/mysql/mysql-connector-python.git

Coding Style

Please follow the MySQL Connector/Python coding standards when contributing with code.

All files should be formatted using the black auto-formatter and isort. This will be run by pre-commit if it's configured.

For C files, the PEP 7 should be followed. A .clang-format configuration is included in the source, so you can manually format the code using the clang-format tool.

Pre-commit Checks

MySQL Connector/Python comes with a pre-commit config file, which manages Git pre-commit hooks. These hooks are useful for identifing issues before committing code.

To use the pre-commit hooks, you first need to install the pre-commit package and then the git hooks:

shell> python -m pip install pre-commit
shell> pre-commit install

The first time pre-commit runs, it will automatically download, install, and run the hooks. Running the hooks for the first time may be slow, but subsequent checks will be significantly faster.

Now, pre-commit will run on every commit.

Running Tests

Any code you contribute needs to pass our test suite. Please follow these steps to run our tests and validate your contributed code.

Run the entire test suite:

shell> python unittests.py --with-mysql=<mysql-dir> --with-mysql-capi=<mysql-capi-dir> --with-protobuf-include-dir=<protobuf-include-dir> --with-protobuf-lib-dir=<protobuf-lib-dir> --with-protoc=<protoc-binary>

Example:

shell> python unittests.py --with-mysql=/usr/local/mysql --with-mysql-capi=/usr/local/mysql --with-protobuf-include-dir=/usr/local/protobuf/include --with-protobuf-lib-dir=/usr/local/protobuf/lib --with-protoc=/usr/local/protobuf/bin/protoc

Test Coverage

When submitting a patch that introduces changes to the source code, you need to make sure that those changes are be accompanied by a proper set of tests that cover 100% of the affected code paths. This is easily auditable by generating proper test coverage HTML and stdout reports using the following commands:

  1. Install the coverage.py package

    shell> python -m pip install coverage

  2. Use coverage run to run your test suite and gather data

    shell> coverage run unittests.py --with-mysql=<mysql-dir> --with-mysql-capi=<mysql-capi-dir> --with-protobuf-include-dir=<protobuf-include-dir> --with-protobuf-lib-dir=<protobuf-lib-dir> --with-protoc=<protoc-binary>

  3. Use coverage report to report on the results

    shell> coverage report -m

  4. For a nicer presentation, use coverage html to get annotated HTML listings

    shell> coverage html

    The HTML will be generated in build/coverage_html.

Getting Help

If you need help or just want to get in touch with us, please use the following resources: