From 8a90d72dbb3bafc0f8f1b3206084db6606a4f972 Mon Sep 17 00:00:00 2001 From: Souma Kanti Ghosh Date: Wed, 11 Sep 2024 17:04:50 +0530 Subject: [PATCH] Added CONTRIBUTING.md and SECURITY.md files in Connector/Python Change-Id: If8352546a735208240540e6daa2ccf4f6e433716 --- CONTRIBUTING.md | 358 ++++++++++++++++++ CONTRIBUTING.rst | 343 ----------------- README.rst | 2 +- SECURITY.md | 30 ++ mysql-connector-python/MANIFEST.in | 3 +- mysql-connector-python/cpydist/bdist.py | 3 +- .../cpydist/bdist_solaris.py | 8 +- .../data/rpm/mysql-connector-python.spec | 2 +- mysql-connector-python/cpydist/sdist.py | 3 +- mysql-connector-python/setup.py | 3 +- mysqlx-connector-python/MANIFEST.in | 3 +- mysqlx-connector-python/cpydist/bdist.py | 3 +- .../cpydist/bdist_solaris.py | 8 +- .../data/rpm/mysql-connector-python.spec | 2 +- mysqlx-connector-python/cpydist/sdist.py | 3 +- mysqlx-connector-python/setup.py | 3 +- 16 files changed, 419 insertions(+), 358 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 CONTRIBUTING.rst create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..eccacbb4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,358 @@ +# 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 [Bugs List](https://bugs.mysql.com/search.php) 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 [MySQL Bug Report page](https://bugs.mysql.com). You will need to reference this user account when you submit your Oracle Contributor Agreement (a.k.a. OCA). +* Sign the Oracle Contributor Agreement. You can find instructions for doing that at the [OCA Page](https://oca.opensource.oracle.com/). +* Develop your pull request. Make sure you are aware of the [environment requirements](https://dev.mysql.com/doc/dev/connector-python/requirements.html) 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](https://github.com/mysql/mysql-connector-python/pulls), you can also submit it directly via [MySQL Bug Report page](https://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. + +* Make sure you have the necessary [prerequisites](https://dev.mysql.com/doc/dev/connector-python/installation.html#prerequisites) for building the project and [Pylint](https://www.pylint.org/) for static code analysis. + +* Clone MySQL Connector/Python + + ```bash + 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](https://github.com/psf/black) auto-formatter and [isort](https://pycqa.github.io/isort/). This will be run by [pre-commit](https://pre-commit.com) if it's configured. + +For C files, the [PEP 7](https://peps.python.org/pep-0007/) should be followed. A ```.clang-format``` configuration is included in the source, so you can manually format the code using the [clang-format](https://clang.llvm.org/docs/ClangFormat.html) 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](https://pre-commit.com) package and then the git hooks: +```bash + 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 `mysql-connector-python` 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: + +```bash + shell> python unittests.py --with-mysql= --with-mysql-capi= +``` + +Example: + +```bash + shell> python unittests.py --with-mysql=/usr/local/mysql --with-mysql-capi=/usr/local/mysql +``` + +The tests can be configured to be launched using an external server or bootstrapping it. The former is preferred (we'll assume so moving forward). + +As you can see, there are several parameters that can be injected into the `unittests` module. The parameters shown above are optional, or a must if you want to run the tests with the *C extension* enabled for the `mysql.connector` module. + +The `with-mysql-capi` flag is needed to build the `C extension` of `mysql.connector`. + +Additionally, there are parameters or flags that can be provided to set values to be used when connecting to the server: + +* **user**: the value stored by the environment variable `MYSQL_USER` is used (if set), otherwise, `root` is used by default. +* **password**: the value of `MYSQL_PASSWORD` is used (if set), otherwise, `empty_string` is used by default. +* **port**: the value of `MYSQL_PORT` is used (if set), otherwise, `3306` is used by default. +* **host**: the value of `MYSQL_HOST` is used (if set), otherwise, `127.0.0.1` (localhost) is used by default. + +The previous defaults conform to the standard or default configuration implemented by the MySQL server. Actually, there are many more flags available, you can explore them via `python unittests.py --help`. + +There are two core flags you can use to control the unit tests selection: + +1. **-t** which is a shortcut for **--test**. This command executes one test module provided the module name:: + +```bash + $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -t cext_cursor +``` + +2. **-T** which is a shortcut for **--one-test**. This command executes a particular test following a finer-grained syntax such as `[.[.]]`: + +```bash + $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_bugs.BugOra16660356 + $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_bugs.BugOra17041240.test_cursor_new +``` + +If you do not provide any flag regarding *control of the unit tests selection*, all available test modules will be run. Some of the available test modules are: + +- abstracts +- authentication +- bugs +- cext_api +- cext_cursor +- connection +- constants +- conversion +- cursor +- errors +- mysql_datatypes +- network +- optionfiles +- pooling +- protocol +- qa_bug16217743 +- qa_caching_sha2_password +- utils + +The list is not complete, but you can deduce and find more module names by inspecting the **tests** folder and its subfolders. + + +# Running `mysqlx-connector-python` 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: + +```bash + shell> python unittests.py --with-mysql= --with-protobuf-include-dir= --with-protobuf-lib-dir= --with-protoc= +``` + +Example: + +```bash + shell> python unittests.py --with-mysql=/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 +``` + +The tests can be configured to be launched using an external server or bootstrapping it. The former is preferred (we'll assume so moving forward). + +As you can see, there are several parameters that can be injected into the `unittests` module. The parameters shown above are optional, or a must if you want to run the tests with the *C extension* enabled for the `mysqlx` module. + +The `protobuf` flags are needed to build the `C extension` of `mysqlx`. + +Additionally, there are parameters or flags that can be provided to set values to be used when connecting to the server: + +* **user**: the value stored by the environment variable `MYSQL_USER` is used (if set), otherwise, `root` is used by default. +* **password**: the value of `MYSQL_PASSWORD` is used (if set), otherwise, `empty_string` is used by default. +* **mysqlx-port**: the value of `MYSQLX_PORT` is used (if set), otherwise, `33060` is used by default. +* **host**: the value of `MYSQL_HOST` is used (if set), otherwise, `127.0.0.1` (localhost) is used by default. + +The previous defaults conform to the standard or default configuration implemented by the MySQL server. Actually, there are many more flags available, you can explore them via `python unittests.py --help`. + +There are two core flags you can use to control the unit tests selection: + +1. **-t** which is a shortcut for **--test**. This command executes one test module provided the module name:: + +```bash + $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -t mysqlx_connection +``` + +2. **-T** which is a shortcut for **--one-test**. This command executes a particular test following a finer-grained syntax such as `[.[.]]`: + +```bash + $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_mysqlx_crud.MySQLxDbDocTests + $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_mysqlx_crud.MySQLxDbDocTests.test_dbdoc_creation +``` + +If you do not provide any flag regarding *control of the unit tests selection*, all available test modules will be run. Some of the available test modules are: + +- mysql_datatypes +- mysqlx_connection +- mysqlx_crud +- mysqlx_errorcode +- mysqlx_pooling + +The list is not complete, but you can deduce and find more module names by inspecting the **tests** folder and its subfolders. + + +## Running `mysql-connector-python` Tests using a Docker Container + +For **Linux** and **macOS** users, there is a script that builds and runs a Docker container which then executes the test suite (*the C extension is built and enabled only if explicitly instructed*). This means no external dependency, apart from a running MySQL server, is needed. + +The script uses the environment variables described previously and introduces a few new ones. These are mostly meant to be used for configuring the Docker container itself. They allow to specify the path to a *Oracle Linux* engine image, the network proxy setup, the URL of the PyPI repository to use and whether you want the **C-EXT** enabled or not. + +* `BASE_IMAGE` (**container-registry.oracle.com/os/oraclelinux:9-slim** by default) +* `HTTP_PROXY` (value of the environment variable in the host by default) +* `HTTPS_PROXY` (value of the environment variable in the host by default) +* `NO_PROXY` (value of the environment variable in the host by default) +* `PYPI_REPOSITORY` (https://pypi.org/pypi by default) +* `MYSQL_CEXT` (used to control the building of the **connector.mysql** C-EXT. If set to ``true`` or ``yes``, the extension is built, otherwise it is not) +* `MYSQL_SOCKET` (described below) + +There is one additional environment variable called `TEST_PATTERN` which can be used to provide a string or a regular expression that is applied for filtering one or more matching unit tests to execute. + +For instance, if you want to run the test module named *cursor* you'd be using: + +```bash + $ TEST_PATTERN='cursor' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +Similarly, if you want to run all tests including the pattern *con* you'd be issuing: + +```bash + $ TEST_PATTERN='.*con.*' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +If you want to run **connector.mysql** tests related to the C-EXT functionality you could use: + +```bash + $ MYSQL_CEXT='true' TEST_PATTERN='cext.*' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +In the examples above, a standard MySQL server configuration is assumed, that's the reason the values for `MYSQL_HOST`, `MYSQL_USER` or `MYSQL_PORT` weren't specified. + +For **Windows** users, you can set up a suitable environment to run bash scripts by installing [Git Bash](https://git-scm.com/), and using the console it provides instead of the natives *PowerShell* or *CMD*. + +Similar to when the tests run on a local environment, the `MYSQL_HOST` variable is only relevant for the functional tests. + +On **Linux**, the variable is optional and the Docker container will run using the "host" network mode whilst tests assume the MySQL server is listening on `localhost`. + +On **macOS** and **Windows**, since containers run on a virtual machine, host loopback addresses are not reachable. In that case, the `MYSQL_HOST` variable is required and should specify the hostname or IP address of the MySQL server. Optionally, you can use `host.docker.internal` as `MYSQL_HOST` if you want to connect to a server hosted locally [reference](https://stackoverflow.com/questions/24319662/from-inside-of-a-docker-container-how-do-i-connect-to-the-localhost-of-the-mach). + +Due to some [know limitations](https://github.com/docker/for-mac/issues/483) on the macOS Docker architecture, Unix socket tests can only run on Linux. In that case, if the `MYSQL_SOCKET` variable is explicitly specified, a shared volume between the host and the container will be created as a mount point from the socket file path in the host and an internal container directory specified as a volume, where the socket file path becomes available. + +That being said, the following are some examples of possible use cases: + +* Running the test modules whose name follows the pattern `c.*` from a mac whose IP is `232.188.98.520`, and the password for `root` is `s3cr3t`. Classic protocol is listening on port `3306`: + +```bash + $ TEST_PATTERN='c.*' MYSQL_HOST='192.168.68.111' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +* Running the whole test suite from Linux with MySQL user account `docker`, and password `s3cr3t`. Classic protocol is listening on port `3308`: + +```bash + $ MYSQL_PORT='3308' MYSQL_USER='docker' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +* Same setup as before but with the **connector.mysql** C-EXT enabled: + +```bash + $ MYSQL_CEXT='true' MYSQL_PORT='3308' MYSQL_USER='docker' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + + +## Running `mysqlx-connector-python` Tests using a Docker Container + +For **Linux** and **macOS** users, there is a script that builds and runs a Docker container which then executes the test suite (*the C extension is built and enabled only if explicitly instructed*). This means no external dependency, apart from a running MySQL server, is needed. + +The script uses the environment variables described previously and introduces a few new ones. These are mostly meant to be used for configuring the Docker container itself. They allow to specify the path to a *Oracle Linux* engine image, the network proxy setup, the URL of the PyPI repository to use and whether you want the **C-EXT** enabled or not. + +* `BASE_IMAGE` (**container-registry.oracle.com/os/oraclelinux:9-slim** by default) +* `HTTP_PROXY` (value of the environment variable in the host by default) +* `HTTPS_PROXY` (value of the environment variable in the host by default) +* `NO_PROXY` (value of the environment variable in the host by default) +* `PYPI_REPOSITORY` (https://pypi.org/pypi by default) +* `MYSQLX_CEXT` (used to control the building of the **mysqlx** C-EXT. If set to `true` or `yes`, the extension is built, otherwise it is not) +* `MYSQL_SOCKET` (described below) + +There is one additional environment variable called `TEST_PATTERN` which can be used to provide a string or a regular expression that is applied for filtering one or more matching unit tests to execute. + +For instance, if you want to run the test module named *cursor* you'd be using:: + +```bash + $ TEST_PATTERN='mysqlx_connection' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +Similarly, if you want to run all tests including the pattern *con* you'd be issuing: + +```bash + $ TEST_PATTERN='.*con.*' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +If you want to run **mysqlx** tests with the C-EXT enabled: + +```bash + $ MYSQLX_CEXT='true' TEST_PATTERN='mysqlx_crud' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + + +In the examples above, a standard MySQL server configuration is assumed, that's the reason the values for `MYSQL_HOST`, `MYSQL_USER` or `MYSQLX_PORT` weren't specified. + +For **Windows** users, you can set up a suitable environment to run bash scripts by installing [Git Bash](https://git-scm.com/), and using the console it provides instead of the natives *PowerShell* or *CMD*. + +Similar to when the tests run on a local environment, the `MYSQL_HOST` variable is only relevant for the functional tests. + +On **Linux**, the variable is optional and the Docker container will run using the "host" network mode whilst tests assume the MySQL server is listening on `localhost`. + +On **macOS** and **Windows**, since containers run on a virtual machine, host loopback addresses are not reachable. In that case, the `MYSQL_HOST` variable is required and should specify the hostname or IP address of the MySQL server. Optionally, you can use `host.docker.internal` as `MYSQL_HOST` if you want to connect to a server hosted locally [reference](https://stackoverflow.com/questions/24319662/from-inside-of-a-docker-container-how-do-i-connect-to-the-localhost-of-the-mach). + +Due to some `know limitations `_ on the macOS Docker architecture, Unix socket tests can only run on Linux. In that case, if the ``MYSQL_SOCKET`` variable is explicitly specified, a shared volume between the host and the container will be created as a mount point from the socket file path in the host and an internal container directory specified as a volume, where the socket file path becomes available. + +That being said, the following there are some examples of possible use cases: + +* Running the test modules whose name follows the pattern `c.*` from a mac whose IP is `232.188.98.520`, and the password for `root` is `s3cr3t`. XDevAPI protocol listening on port `33060`: + +```bash + $ TEST_PATTERN='c.*' MYSQL_HOST='192.168.68.111' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh +``` + +* Running the *mysqlx_crud* test module from Linux with MySQL user account `root`, and password `empty_string`. XDevAPI protocol listening on port `33070`: + +```bash + $ MYSQLX_PORT='33070' TEST_PATTERN='mysqlx_crud' ./tests/docker/runner.sh +``` + + +## 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](https://github.com/nedbat/coveragepy) package using the following command: + +```bash + shell> python -m pip install coverage +``` + +2) Use coverage run to run your test suite (assuming `mysql-connector-python`) and gather data: + +```bash + shell> coverage run unittests.py --with-mysql= --with-mysql-capi= +``` + +3) Use `coverage report` to report on the results: + +```bash + shell> coverage report -m +``` + +4) For a nicer presentation, use ``coverage html`` to get annotated HTML listings, The HTML will be generated in `build/coverage_html`: + +```bash + shell> coverage html +``` + +## Getting Help + +If you need help or just want to get in touch with us, please use the following resources: + +- [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/) +- [MySQL Connector/Python X DevAPI Reference](https://dev.mysql.com/doc/dev/connector-python/) +- [MySQL Connector/Python Forum](http://forums.mysql.com/list.php?50) +- [MySQL Public Bug Tracker](https://bugs.mysql.com) +- [Slack](https://mysqlcommunity.slack.com) ([Sign-up](https://lefred.be/mysql-community-on-slack/) is required if you do not have an Oracle account) +- [Stack Overflow](https://stackoverflow.com/questions/tagged/mysql-connector-python) +- [InsideMySQL.com Connectors Blog](https://insidemysql.com/category/mysql-development/connectors/) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 65d50429..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,343 +0,0 @@ -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 (a.k.a. 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 - - .. code-block:: bash - - 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: - - .. code-block:: bash - - 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 `mysql-connector-python` 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: - - .. code-block:: bash - - shell> python unittests.py --with-mysql= --with-mysql-capi= - -Example: - - .. code-block:: sh - - shell> python unittests.py --with-mysql=/usr/local/mysql --with-mysql-capi=/usr/local/mysql - -The tests can be configured to be launched using an external server or bootstrapping it. The former is preferred (we'll assume so moving forward). - -As you can see, there are several parameters that can be injected into the ``unittests`` module. The parameters shown above are optional, or a must if you want to run the tests with the *C extension* enabled for the ``mysql.connector`` module. - -The ``with-mysql-capi`` flag is needed to build the `C extension` of ``mysql.connector``. - -Additionally, there are parameters or flags that can be provided to set values to be used when connecting to the server: - -* **user**: the value stored by the environment variable ``MYSQL_USER`` is used (if set), otherwise, ``root`` is used by default. -* **password**: the value of ``MYSQL_PASSWORD`` is used (if set), otherwise, ``empty_string`` is used by default. -* **port**: the value of ``MYSQL_PORT`` is used (if set), otherwise, ``3306`` is used by default. -* **host**: the value of ``MYSQL_HOST`` is used (if set), otherwise, ``127.0.0.1`` (localhost) is used by default. - -The previous defaults conform to the standard or default configuration implemented by the MySQL server. Actually, there are many more flags available, you can explore them via ``python unittests.py --help``. - -There are two core flags you can use to control the unit tests selection: - -1. **-t** which is a shortcut for **--test**. This command executes one test module provided the module name:: - - $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -t cext_cursor - -2. **-T** which is a shortcut for **--one-test**. This command executes a particular test following a finer-grained syntax such as ``[.[.]]``:: - - $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_bugs.BugOra16660356 - $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_bugs.BugOra17041240.test_cursor_new - -If you do not provide any flag regarding *control of the unit tests selection*, all available test modules will be run. Some of the available test modules are: - -- abstracts -- authentication -- bugs -- cext_api -- cext_cursor -- connection -- constants -- conversion -- cursor -- errors -- mysql_datatypes -- network -- optionfiles -- pooling -- protocol -- qa_bug16217743 -- qa_caching_sha2_password -- utils - -The list is not complete, but you can deduce and find more module names by inspecting the **tests** folder and its subfolders. - - -Running `mysqlx-connector-python` 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: - - .. code-block:: bash - - shell> python unittests.py --with-mysql= --with-protobuf-include-dir= --with-protobuf-lib-dir= --with-protoc= - -Example: - - .. code-block:: sh - - shell> python unittests.py --with-mysql=/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 - -The tests can be configured to be launched using an external server or bootstrapping it. The former is preferred (we'll assume so moving forward). - -As you can see, there are several parameters that can be injected into the ``unittests`` module. The parameters shown above are optional, or a must if you want to run the tests with the *C extension* enabled for the ``mysqlx`` module. - -The ``protobuf`` flags are needed to build the `C extension` of ``mysqlx``. - -Additionally, there are parameters or flags that can be provided to set values to be used when connecting to the server: - -* **user**: the value stored by the environment variable ``MYSQL_USER`` is used (if set), otherwise, ``root`` is used by default. -* **password**: the value of ``MYSQL_PASSWORD`` is used (if set), otherwise, ``empty_string`` is used by default. -* **mysqlx-port**: the value of ``MYSQLX_PORT`` is used (if set), otherwise, ``33060`` is used by default. -* **host**: the value of ``MYSQL_HOST`` is used (if set), otherwise, ``127.0.0.1`` (localhost) is used by default. - -The previous defaults conform to the standard or default configuration implemented by the MySQL server. Actually, there are many more flags available, you can explore them via ``python unittests.py --help``. - -There are two core flags you can use to control the unit tests selection: - -1. **-t** which is a shortcut for **--test**. This command executes one test module provided the module name:: - - $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -t mysqlx_connection - -2. **-T** which is a shortcut for **--one-test**. This command executes a particular test following a finer-grained syntax such as ``[.[.]]``:: - - $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_mysqlx_crud.MySQLxDbDocTests - $ python unittests.py --use-external-server --verbosity 2 --password=$MYPASS -T tests.test_mysqlx_crud.MySQLxDbDocTests.test_dbdoc_creation - -If you do not provide any flag regarding *control of the unit tests selection*, all available test modules will be run. Some of the available test modules are: - -- mysql_datatypes -- mysqlx_connection -- mysqlx_crud -- mysqlx_errorcode -- mysqlx_pooling - -The list is not complete, but you can deduce and find more module names by inspecting the **tests** folder and its subfolders. - - -Running `mysql-connector-python` Tests using a Docker Container ---------------------------------------------------------------- - -For **Linux** and **macOS** users, there is a script that builds and runs a Docker container which then executes the test suite (*the C extension is built and enabled only if explicitly instructed*). This means no external dependency, apart from a running MySQL server, is needed. - -The script uses the environment variables described previously and introduces a few new ones. These are mostly meant to be used for configuring the Docker container itself. They allow to specify the path to a *Oracle Linux* engine image, the network proxy setup, the URL of the PyPI repository to use and whether you want the **C-EXT** enabled or not. - -* ``BASE_IMAGE`` (**container-registry.oracle.com/os/oraclelinux:9-slim** by default) -* ``HTTP_PROXY`` (value of the environment variable in the host by default) -* ``HTTPS_PROXY`` (value of the environment variable in the host by default) -* ``NO_PROXY`` (value of the environment variable in the host by default) -* ``PYPI_REPOSITORY`` (https://pypi.org/pypi by default) -* ``MYSQL_CEXT`` (used to control the building of the **connector.mysql** C-EXT. If set to ``true`` or ``yes``, the extension is built, otherwise it is not) -* ``MYSQL_SOCKET`` (described below) - -There is one additional environment variable called ``TEST_PATTERN`` which can be used to provide a string or a regular expression that is applied for filtering one or more matching unit tests to execute. - -For instance, if you want to run the test module named *cursor* you'd be using:: - - $ TEST_PATTERN='cursor' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -Similarly, if you want to run all tests including the pattern *con* you'd be issuing:: - - $ TEST_PATTERN='.*con.*' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -If you want to run **connector.mysql** tests related to the C-EXT functionality you could use:: - - $ MYSQL_CEXT='true' TEST_PATTERN='cext.*' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -In the examples above, a standard MySQL server configuration is assumed, that's the reason the values for ``MYSQL_HOST``, ``MYSQL_USER`` or ``MYSQL_PORT`` weren't specified. - -For **Windows** users, you can set up a suitable environment to run bash scripts by installing `Git Bash `_, and using the console it provides instead of the natives *PowerShell* or *CMD*. - -Similar to when the tests run on a local environment, the ``MYSQL_HOST`` variable is only relevant for the functional tests. - -On **Linux**, the variable is optional and the Docker container will run using the "host" network mode whilst tests assume the MySQL server is listening on ``localhost``. - -On **macOS** and **Windows**, since containers run on a virtual machine, host loopback addresses are not reachable. In that case, the ``MYSQL_HOST`` variable is required and should specify the hostname or IP address of the MySQL server. Optionally, you can use ``host.docker.internal`` as ``MYSQL_HOST`` if you want to connect to a server hosted locally `[reference] `_. - -Due to some `know limitations `_ on the macOS Docker architecture, Unix socket tests can only run on Linux. In that case, if the ``MYSQL_SOCKET`` variable is explicitly specified, a shared volume between the host and the container will be created as a mount point from the socket file path in the host and an internal container directory specified as a volume, where the socket file path becomes available. - -That being said, the following are some examples of possible use cases: - -* Running the test modules whose name follows the pattern ``c.*`` from a mac whose IP is ``232.188.98.520``, and the password for ``root`` is ``s3cr3t``. Classic protocol is listening on port ``3306``:: - - $ TEST_PATTERN='c.*' MYSQL_HOST='192.168.68.111' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -* Running the whole test suite from Linux with MySQL user account ``docker``, and password ``s3cr3t``. Classic protocol is listening on port ``3308``:: - - $ MYSQL_PORT='3308' MYSQL_USER='docker' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -* Same setup as before but with the **connector.mysql** C-EXT enabled:: - - $ MYSQL_CEXT='true' MYSQL_PORT='3308' MYSQL_USER='docker' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - - -Running `mysqlx-connector-python` Tests using a Docker Container ----------------------------------------------------------------- - -For **Linux** and **macOS** users, there is a script that builds and runs a Docker container which then executes the test suite (*the C extension is built and enabled only if explicitly instructed*). This means no external dependency, apart from a running MySQL server, is needed. - -The script uses the environment variables described previously and introduces a few new ones. These are mostly meant to be used for configuring the Docker container itself. They allow to specify the path to a *Oracle Linux* engine image, the network proxy setup, the URL of the PyPI repository to use and whether you want the **C-EXT** enabled or not. - -* ``BASE_IMAGE`` (**container-registry.oracle.com/os/oraclelinux:9-slim** by default) -* ``HTTP_PROXY`` (value of the environment variable in the host by default) -* ``HTTPS_PROXY`` (value of the environment variable in the host by default) -* ``NO_PROXY`` (value of the environment variable in the host by default) -* ``PYPI_REPOSITORY`` (https://pypi.org/pypi by default) -* ``MYSQLX_CEXT`` (used to control the building of the **mysqlx** C-EXT. If set to ``true`` or ``yes``, the extension is built, otherwise it is not) -* ``MYSQL_SOCKET`` (described below) - -There is one additional environment variable called ``TEST_PATTERN`` which can be used to provide a string or a regular expression that is applied for filtering one or more matching unit tests to execute. - -For instance, if you want to run the test module named *cursor* you'd be using:: - - $ TEST_PATTERN='mysqlx_connection' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -Similarly, if you want to run all tests including the pattern *con* you'd be issuing:: - - $ TEST_PATTERN='.*con.*' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -If you want to run **mysqlx** tests with the C-EXT enabled:: - - $ MYSQLX_CEXT='true' TEST_PATTERN='mysqlx_crud' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - - -In the examples above, a standard MySQL server configuration is assumed, that's the reason the values for ``MYSQL_HOST``, ``MYSQL_USER`` or ``MYSQLX_PORT`` weren't specified. - -For **Windows** users, you can set up a suitable environment to run bash scripts by installing `Git Bash `_, and using the console it provides instead of the natives *PowerShell* or *CMD*. - -Similar to when the tests run on a local environment, the ``MYSQL_HOST`` variable is only relevant for the functional tests. - -On **Linux**, the variable is optional and the Docker container will run using the "host" network mode whilst tests assume the MySQL server is listening on ``localhost``. - -On **macOS** and **Windows**, since containers run on a virtual machine, host loopback addresses are not reachable. In that case, the ``MYSQL_HOST`` variable is required and should specify the hostname or IP address of the MySQL server. Optionally, you can use ``host.docker.internal`` as ``MYSQL_HOST`` if you want to connect to a server hosted locally `[reference] `_. - -Due to some `know limitations `_ on the macOS Docker architecture, Unix socket tests can only run on Linux. In that case, if the ``MYSQL_SOCKET`` variable is explicitly specified, a shared volume between the host and the container will be created as a mount point from the socket file path in the host and an internal container directory specified as a volume, where the socket file path becomes available. - -That being said, the following there are some examples of possible use cases: - -* Running the test modules whose name follows the pattern ``c.*`` from a mac whose IP is ``232.188.98.520``, and the password for ``root`` is ``s3cr3t``. XDevAPI protocol listening on port ``33060``:: - - $ TEST_PATTERN='c.*' MYSQL_HOST='192.168.68.111' MYSQL_PASSWORD='s3cr3t' ./tests/docker/runner.sh - -* Running the *mysqlx_crud* test module from Linux with MySQL user account ``root``, and password ``empty_string``. XDevAPI protocol listening on port ``33070``:: - - $ MYSQLX_PORT='33070' TEST_PATTERN='mysqlx_crud' ./tests/docker/runner.sh - - -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 - - .. code-block:: bash - - shell> python -m pip install coverage - -2) Use coverage run to run your test suite (assuming `mysql-connector-python`) and gather data - - .. code-block:: bash - - shell> coverage run unittests.py --with-mysql= --with-mysql-capi= - -3) Use ``coverage report`` to report on the results - - .. code-block:: bash - - shell> coverage report -m - -4) For a nicer presentation, use ``coverage html`` to get annotated HTML listings - - .. code-block:: bash - - 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: - -- `MySQL Connector/Python Developer Guide `_ -- `MySQL Connector/Python X DevAPI Reference `_ -- `MySQL Connector/Python Forum `_ -- `MySQL Public Bug Tracker `_ -- `Slack `_ (`Sign-up `_ required if you do not have an Oracle account) -- `Stack Overflow `_ -- `InsideMySQL.com Connectors Blog `_ diff --git a/README.rst b/README.rst index 697fdd78..04894727 100644 --- a/README.rst +++ b/README.rst @@ -196,7 +196,7 @@ Contributing ------------ There are a few ways to contribute to the Connector/Python code. Please refer -to the `contributing guidelines `_ for additional information. +to the `contributing guidelines `_ for additional information. License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..f3e2bab7 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,30 @@ +# Reporting security vulnerabilities + +Oracle values the independent security research community and believes that +responsible disclosure of security vulnerabilities helps us ensure the security +and privacy of all our users. + +Please do NOT raise a GitHub Issue to report a security vulnerability. If you +believe you have found a security vulnerability, please submit a report to +secalert_us@oracle.com preferably with a proof of concept. Please review +some additional information on how to report security vulnerabilities to Oracle +(see https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html) +We encourage people who contact Oracle Security to use email encryption using +our encryption key (see https://www.oracle.com/security-alerts/encryptionkey.html) + +We ask that you do not use other channels or contact the project maintainers +directly. + +# Security updates, alerts and bulletins + +Security updates will be released on a regular cadence. Many of our projects +will typically release security fixes in conjunction with the Oracle Critical Patch +Update program. Additional information, including past advisories, is available on our +security alerts page at https://www.oracle.com/security-alerts/ + +# Security-related information + +We will provide security related information such as a threat model, considerations +for secure use, or any known security issues in our documentation. Please note +that labs and sample code are intended to demonstrate a concept and may not be +sufficiently hardened for production use. \ No newline at end of file diff --git a/mysql-connector-python/MANIFEST.in b/mysql-connector-python/MANIFEST.in index a37734a1..d99a7b4e 100644 --- a/mysql-connector-python/MANIFEST.in +++ b/mysql-connector-python/MANIFEST.in @@ -1,7 +1,8 @@ include README.txt include README.rst include LICENSE.txt -include CONTRIBUTING.rst +include CONTRIBUTING.md +include SECURITY.md include CHANGES.txt include setup.py include unittests.py diff --git a/mysql-connector-python/cpydist/bdist.py b/mysql-connector-python/cpydist/bdist.py index 3d8a4dd1..26c4a267 100644 --- a/mysql-connector-python/cpydist/bdist.py +++ b/mysql-connector-python/cpydist/bdist.py @@ -200,7 +200,8 @@ def run(self): ("README.txt", "README.txt"), ("LICENSE.txt", "LICENSE.txt"), ("README.rst", "README.rst"), - ("CONTRIBUTING.rst", "CONTRIBUTING.rst"), + ("CONTRIBUTING.md", "CONTRIBUTING.md"), + ("SECURITY.md", "SECURITY.md"), ("docs/INFO_SRC", "INFO_SRC"), ("docs/INFO_BIN", "INFO_BIN"), ] diff --git a/mysql-connector-python/cpydist/bdist_solaris.py b/mysql-connector-python/cpydist/bdist_solaris.py index 2a8b9fed..b07bfbed 100644 --- a/mysql-connector-python/cpydist/bdist_solaris.py +++ b/mysql-connector-python/cpydist/bdist_solaris.py @@ -208,8 +208,12 @@ def _prepare_pkg_base(self, template_name, data_dir, root=""): os.path.join(data_path, "README.rst"), ), ( - os.path.join(cwd, "CONTRIBUTING.rst"), - os.path.join(data_path, "CONTRIBUTING.rst"), + os.path.join(cwd, "CONTRIBUTING.md"), + os.path.join(data_path, "CONTRIBUTING.md"), + ), + ( + os.path.join(cwd, "SECURITY.md"), + os.path.join(data_path, "SECURITY.md"), ), ] diff --git a/mysql-connector-python/cpydist/data/rpm/mysql-connector-python.spec b/mysql-connector-python/cpydist/data/rpm/mysql-connector-python.spec index bbe303b6..c221f377 100644 --- a/mysql-connector-python/cpydist/data/rpm/mysql-connector-python.spec +++ b/mysql-connector-python/cpydist/data/rpm/mysql-connector-python.spec @@ -169,7 +169,7 @@ cd mysql-connector-python %{?scl:EOF} %files -n mysql-connector-python3%{?product_suffix} -%doc LICENSE.txt CHANGES.txt README.txt README.rst CONTRIBUTING.rst mysql-connector-python/docs/INFO_SRC mysql-connector-python/docs/INFO_BIN +%doc LICENSE.txt CHANGES.txt README.txt README.rst CONTRIBUTING.md SECURITY.md mysql-connector-python/docs/INFO_SRC mysql-connector-python/docs/INFO_BIN %{python3_sitearch}/mysql %{python3_sitearch}/mysql_connector_python-*.egg-info %{python3_sitearch}/_mysql_connector.cpython*.so diff --git a/mysql-connector-python/cpydist/sdist.py b/mysql-connector-python/cpydist/sdist.py index 318b50ac..3ab6c9b5 100644 --- a/mysql-connector-python/cpydist/sdist.py +++ b/mysql-connector-python/cpydist/sdist.py @@ -262,7 +262,8 @@ def run(self): ("README.txt", "README.txt"), ("LICENSE.txt", "LICENSE.txt"), ("README.rst", "README.rst"), - ("CONTRIBUTING.rst", "CONTRIBUTING.rst"), + ("CONTRIBUTING.md", "CONTRIBUTING.md"), + ("SECURITY.md", "SECURITY.md"), ("docs/INFO_SRC", "INFO_SRC"), ("docs/INFO_BIN", "INFO_BIN"), ] diff --git a/mysql-connector-python/setup.py b/mysql-connector-python/setup.py index 0ae3c593..ae6cbf7b 100644 --- a/mysql-connector-python/setup.py +++ b/mysql-connector-python/setup.py @@ -53,7 +53,8 @@ "README.rst", "LICENSE.txt", "CHANGES.txt", - "CONTRIBUTING.rst", + "CONTRIBUTING.md", + "SECURITY.md", ) VERSION_TEXT = "999.0.0" diff --git a/mysqlx-connector-python/MANIFEST.in b/mysqlx-connector-python/MANIFEST.in index 513b1f03..b6af1315 100644 --- a/mysqlx-connector-python/MANIFEST.in +++ b/mysqlx-connector-python/MANIFEST.in @@ -1,7 +1,8 @@ include README.txt include README.rst include LICENSE.txt -include CONTRIBUTING.rst +include CONTRIBUTING.md +include SECURITY.md include CHANGES.txt include setup.py include unittests.py diff --git a/mysqlx-connector-python/cpydist/bdist.py b/mysqlx-connector-python/cpydist/bdist.py index 68fa5c23..2c0d8093 100644 --- a/mysqlx-connector-python/cpydist/bdist.py +++ b/mysqlx-connector-python/cpydist/bdist.py @@ -200,7 +200,8 @@ def run(self): ("README.txt", "README.txt"), ("LICENSE.txt", "LICENSE.txt"), ("README.rst", "README.rst"), - ("CONTRIBUTING.rst", "CONTRIBUTING.rst"), + ("CONTRIBUTING.md", "CONTRIBUTING.md"), + ("SECURITY.md", "SECURITY.md"), ("docs/INFO_SRC", "INFO_SRC"), ("docs/INFO_BIN", "INFO_BIN"), ] diff --git a/mysqlx-connector-python/cpydist/bdist_solaris.py b/mysqlx-connector-python/cpydist/bdist_solaris.py index 2a8b9fed..b07bfbed 100644 --- a/mysqlx-connector-python/cpydist/bdist_solaris.py +++ b/mysqlx-connector-python/cpydist/bdist_solaris.py @@ -208,8 +208,12 @@ def _prepare_pkg_base(self, template_name, data_dir, root=""): os.path.join(data_path, "README.rst"), ), ( - os.path.join(cwd, "CONTRIBUTING.rst"), - os.path.join(data_path, "CONTRIBUTING.rst"), + os.path.join(cwd, "CONTRIBUTING.md"), + os.path.join(data_path, "CONTRIBUTING.md"), + ), + ( + os.path.join(cwd, "SECURITY.md"), + os.path.join(data_path, "SECURITY.md"), ), ] diff --git a/mysqlx-connector-python/cpydist/data/rpm/mysql-connector-python.spec b/mysqlx-connector-python/cpydist/data/rpm/mysql-connector-python.spec index 46c622d5..57998ba6 100644 --- a/mysqlx-connector-python/cpydist/data/rpm/mysql-connector-python.spec +++ b/mysqlx-connector-python/cpydist/data/rpm/mysql-connector-python.spec @@ -168,7 +168,7 @@ cd mysqlx-connector-python sed -i -e '/protobuf/d' %{buildroot}%{python3_sitearch}/mysqlx_connector_python-*.egg-info/requires.txt %files -n mysqlx-connector-python3%{?product_suffix} -%doc LICENSE.txt CHANGES.txt README.txt README.rst CONTRIBUTING.rst mysqlx-connector-python/docs/INFO_SRC mysqlx-connector-python/docs/INFO_BIN +%doc LICENSE.txt CHANGES.txt README.txt README.rst CONTRIBUTING.md SECURITY.md mysqlx-connector-python/docs/INFO_SRC mysqlx-connector-python/docs/INFO_BIN %{python3_sitearch}/mysqlx %{python3_sitearch}/mysqlx_connector_python-*.egg-info %{python3_sitearch}/_mysqlxpb.cpython*.so diff --git a/mysqlx-connector-python/cpydist/sdist.py b/mysqlx-connector-python/cpydist/sdist.py index 318b50ac..3ab6c9b5 100644 --- a/mysqlx-connector-python/cpydist/sdist.py +++ b/mysqlx-connector-python/cpydist/sdist.py @@ -262,7 +262,8 @@ def run(self): ("README.txt", "README.txt"), ("LICENSE.txt", "LICENSE.txt"), ("README.rst", "README.rst"), - ("CONTRIBUTING.rst", "CONTRIBUTING.rst"), + ("CONTRIBUTING.md", "CONTRIBUTING.md"), + ("SECURITY.md", "SECURITY.md"), ("docs/INFO_SRC", "INFO_SRC"), ("docs/INFO_BIN", "INFO_BIN"), ] diff --git a/mysqlx-connector-python/setup.py b/mysqlx-connector-python/setup.py index 0db79a41..b409a65b 100644 --- a/mysqlx-connector-python/setup.py +++ b/mysqlx-connector-python/setup.py @@ -54,7 +54,8 @@ "README.rst", "LICENSE.txt", "CHANGES.txt", - "CONTRIBUTING.rst", + "CONTRIBUTING.md", + "SECURITY.md", )