|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We welcome your contributions! There are multiple ways to contribute. |
| 4 | + |
| 5 | +## Issues |
| 6 | + |
| 7 | +For bugs or enhancement requests, please file a GitHub issue unless it's security related. When filing a bug remember that the better written the bug is, the more likely it is to be fixed. If you think you've found a security vulnerability, do not raise a GitHub issue and follow the instructions on our Security Policy. |
| 8 | + |
| 9 | +## Contributing Code |
| 10 | + |
| 11 | +We welcome your code contributions. To get started, you will need to sign the [Oracle Contributor Agreement (OCA)](https://oca.opensource.oracle.com/). |
| 12 | + |
| 13 | +For pull requests to be accepted, the bottom of your commit message must have the following line using the name and e-mail address you used for the OCA. |
| 14 | + |
| 15 | +```text |
| 16 | +Signed-off-by: Your Name <[email protected]> |
| 17 | +``` |
| 18 | + |
| 19 | +This can be automatically added to pull requests by committing with: |
| 20 | + |
| 21 | +```text |
| 22 | +git commit --signoff |
| 23 | +``` |
| 24 | + |
| 25 | +Only pull requests from committers that can be verified as having signed the OCA can be accepted. |
| 26 | + |
| 27 | +## Pull request process |
| 28 | + |
| 29 | +1. Fork this repository |
| 30 | +2. Create a branch in your fork to implement the changes. We recommend using the issue number as part of your branch name, e.g. 1234-fixes |
| 31 | +3. Ensure that any documentation is updated with the changes that are required by your fix. |
| 32 | +4. Ensure that any samples are updated if the base image has been changed. |
| 33 | +5. Submit the pull request. Do not leave the pull request blank. Explain exactly what your changes are meant to do and provide simple steps on how to validate your changes. Ensure that you reference the issue you created as well. |
| 34 | +6. We will review your PR before it is merged. |
| 35 | + |
| 36 | +## Setting the development environment |
| 37 | + |
| 38 | +Clone this repo in a directory where you would like to work from |
| 39 | + |
| 40 | +```bash |
| 41 | +git clone ssh:// [email protected]:oracle/dbt-oracle.git |
| 42 | +``` |
| 43 | + |
| 44 | +Create a virtual environment |
| 45 | +```bash |
| 46 | +python3 -m venv .db-oracle-env |
| 47 | +source .db-oracle-env/bin/activate |
| 48 | +``` |
| 49 | + |
| 50 | +Install development requirements |
| 51 | +```bash |
| 52 | +pip install --upgrade pip |
| 53 | +pip install -r requirements_dev,txt |
| 54 | +``` |
| 55 | + |
| 56 | +Install core dependencies |
| 57 | +```bash |
| 58 | +pip install -r requirements.txt |
| 59 | +``` |
| 60 | + |
| 61 | +Run the following command. |
| 62 | +```bash |
| 63 | +python3 setup.py develop |
| 64 | +``` |
| 65 | +This command allows you to deploy the project’s source for use in one or more “staging areas” where it will be available for importing. This deployment is done in such a way that changes to the project source are immediately available in the staging area(s), without needing to run a build or install step after each change. |
| 66 | + |
| 67 | +It creates a special `.egg-link` file in the deployment directory, that links to the source code. |
| 68 | +And if the deployment directory is Python's site-packages directory, it will also update the |
| 69 | +`easy-install.pth` file to include the source code, thereby making it available on `sys.path` for all programs using the Python installation |
| 70 | + |
| 71 | +For details check - https://setuptools.pypa.io/en/latest/userguide/commands.html#develop |
| 72 | + |
| 73 | +Once done with development, the project can be removed from the staging area using |
| 74 | + |
| 75 | +```bash |
| 76 | +python3 setup.py develop --uninstall |
| 77 | +``` |
| 78 | + |
| 79 | +## Testing <a name='testing'></a> |
| 80 | + |
| 81 | +### Environment variables <a name='environment-variables'></a> |
| 82 | + |
| 83 | +The following environment variables should be set to test `dbt-oracle` |
| 84 | + |
| 85 | +```bash |
| 86 | + # cx_oracle needs lib_dir parameter pointing to the folder |
| 87 | + # containing the libraries from an unzipped Instant Client Basic or Basic Light package. |
| 88 | + # If lib_dir is not passed client libraries are looked for in the Operating system search path |
| 89 | + # or set in the following environment variables. |
| 90 | + DYLD_LIBRARY_PATH # For MacOS |
| 91 | + LD_LIBRARY_PATH # For Linux |
| 92 | + |
| 93 | + # For ADB, cx_oracle will need the path to the folder |
| 94 | + # containing client wallet, sqlnet.ora and tnsnames.ora |
| 95 | + TNS_ADMIN |
| 96 | + |
| 97 | + # Database connection config - dbt specific variables |
| 98 | + DBT_ORACLE_USER |
| 99 | + DBT_ORACLE_HOST |
| 100 | + DBT_ORACLE_PORT |
| 101 | + DBT_ORACLE_SERVICE |
| 102 | + DBT_ORACLE_PASSWORD |
| 103 | + DBT_ORACLE_DATABASE |
| 104 | + DBT_ORACLE_SCHEMA |
| 105 | +``` |
| 106 | + |
| 107 | +### Adapter Plugin Tests <a name='adapter-plugin-tests'></a> |
| 108 | + |
| 109 | +dbt-labs has built a package [dbt-adapter-tests](https://github.com/dbt-labs/dbt-adapter-tests) which defines a test suite for adapter plugins |
| 110 | + |
| 111 | +It can be installed using |
| 112 | +```bash |
| 113 | +pip install pytest-dbt-adapter |
| 114 | +``` |
| 115 | +The spec file [oracle.dbtspec](tests/oracle.dbtspec) lists all test sequences |
| 116 | + |
| 117 | +To run the test cases for Python 3.7, 3.8 and 3.9 type the following command |
| 118 | +```bash |
| 119 | +pytest tests/oracle.dbtspec tests/test_config.py # For Python 3.7, 3.8 and 3.9 |
| 120 | + |
| 121 | +or |
| 122 | + |
| 123 | +pytest tests/oracle_py36.dbtspect tests/test_config.py # For Python 3.6 |
| 124 | +``` |
| 125 | +All tests are passing for Python 3.7, 3.8 and 3.9 |
| 126 | +```text |
| 127 | +tests/oracle.dbtspec::test_dbt_empty |
| 128 | +tests/oracle.dbtspec::test_dbt_base |
| 129 | +tests/oracle.dbtspec::test_dbt_ephemeral |
| 130 | +tests/oracle.dbtspec::test_dbt_incremental |
| 131 | +tests/oracle.dbtspec::test_dbt_snapshot_strategy_timestamp |
| 132 | +tests/oracle.dbtspec::test_dbt_snapshot_strategy_check_cols |
| 133 | +tests/oracle.dbtspec::test_dbt_schema_test |
| 134 | +tests/oracle.dbtspec::test_dbt_data_test |
| 135 | +tests/oracle.dbtspec::test_dbt_ephemeral_data_tests |
| 136 | +``` |
| 137 | + |
| 138 | +Known failing test only for Python 3.6 |
| 139 | +```text |
| 140 | +FAILED tests/oracle.dbtspec::test_dbt_empty |
| 141 | +``` |
| 142 | + |
| 143 | + |
| 144 | +### Different Python versions <a name='different-python-versions'></a> |
| 145 | + |
| 146 | +`tox` is a command line tool to check if the package installs correctly for different python versions. It also runs all the tests in each of the environments. Check the configuration file [tox.ini](tox.ini) for details. |
| 147 | + |
| 148 | +To run tox, from command line type |
| 149 | +```bash |
| 150 | +tox |
| 151 | +``` |
| 152 | +If all tests succeed for all python environments, you will see the below output. |
| 153 | + |
| 154 | +```text |
| 155 | + py36: commands succeeded |
| 156 | + py37: commands succeeded |
| 157 | + py38: commands succeeded |
| 158 | + py39: commands succeeded |
| 159 | + congratulations :) |
| 160 | +``` |
| 161 | +For each environment, you can also see the test runtime as summary |
| 162 | +```text |
| 163 | + py36 - 12 passed, 8 warnings in 693.73s (0:11:33) |
| 164 | + py37 - 13 passed, 9 warnings in 673.23s (0:11:13) |
| 165 | + py38 - 13 passed, 9 warnings in 745.82s (0:12:25) |
| 166 | + py39 - 13 passed, 9 warnings in 693.90s (0:11:33) |
| 167 | +``` |
| 168 | + |
| 169 | +## Build & Packaging <a name='build--packaging'></a> |
| 170 | + |
| 171 | +This section explains how to build dbt-oracle package, generate the distribution archive and upload it to Python Package Index (PyPI). |
| 172 | + |
| 173 | +[pyproject.toml](pyproject.toml) tells build tools like `pip` and `build` what is required to build the project. We use the standard `setuptools` |
| 174 | + |
| 175 | +```toml |
| 176 | +# pyproject.toml |
| 177 | +[build-system] |
| 178 | +requires = ['setuptools', 'wheel'] |
| 179 | +build-backend = "setuptools.build_meta" |
| 180 | +``` |
| 181 | + |
| 182 | +### Configuring Metadata <a name='configuring-metadata'></a> |
| 183 | + |
| 184 | +- Static metadata |
| 185 | + - [setup.cfg](setup.cfg) is a configuration file for `setuptools`. It is guaranteed to be the same everytime |
| 186 | + |
| 187 | +- Dynamic metadata |
| 188 | + - [setup.py](setup.py) is the build script for `setuptools` |
| 189 | + - It is used to determine any items at install time. All Extension modules need to go into setup.py |
| 190 | + |
| 191 | +### Generating distribution archives <a name='generating-distribution-archives'></a> |
| 192 | + |
| 193 | +Run the command |
| 194 | + |
| 195 | +```bash |
| 196 | +python3 -m build |
| 197 | + |
| 198 | +or |
| 199 | + |
| 200 | +python3 setup.py bdist_wheel |
| 201 | +``` |
| 202 | + |
| 203 | +This will generate 2 files in the `dist` folder. |
| 204 | +The `tar.gz` file is the source archive and `.whl` is the built distribution. Newer pip versions will install the built distribution but will fall back to |
| 205 | +source archive if needed. |
| 206 | + |
| 207 | +```text |
| 208 | +-rw-r--r-- 1 29323 Nov 24 12:56 dbt-oracle-0.4.4.tar.gz |
| 209 | +-rw-r--r-- 1 25599 Nov 24 12:56 dbt_oracle-0.4.4-py3-none-any.whl |
| 210 | +``` |
| 211 | + |
| 212 | +### Upload to PyPI <a name='upload-distribution-archives'></a> |
| 213 | + |
| 214 | +Finally, the package can be uploaded to the Python Package Index (PyPI) using `twine` |
| 215 | + |
| 216 | +Install `twine` |
| 217 | +```bash |
| 218 | +pip install --upgrade twine |
| 219 | +``` |
| 220 | + |
| 221 | +Run the upload command to upload all archives in dist/* |
| 222 | + |
| 223 | +```bash |
| 224 | +python3 -m twine upload dist/* |
| 225 | +``` |
| 226 | + |
| 227 | + |
| 228 | +## Code of Conduct |
| 229 | + |
| 230 | +Follow the [Golden Rule](https://en.wikipedia.org/wiki/Golden_Rule). If you'd like more specific guidelines see the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct/) |
0 commit comments