Merge pull request #347 from BentsiLeviav/main

Create CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contribution Guide for dbt-ClickHouse Adapter
+
+## Introduction
+
+Thank you for considering contributing to the dbt-ClickHouse adapter! We value your contributions and appreciate your
+efforts to improve the adapter. This guide will help you get started with the contribution process.
+
+## Getting Started
+
+### 1. Fork the Repository
+
+Start by forking the repository on GitHub. This will create a copy of the repository under your own GitHub account.
+
+### 2. Set Up Environment
+
+* Make sure Python is installed locally, please refer to [dbt's python compatibility](https://docs.getdbt.com/faqs/Core/install-python-compatibility) (We recommend using version 3.12+).
+* Create a dedicated virtual environment (optional but recommended)
+* Install all the development requirements:
+    ```bash
+    pip install -r dev_requirements.txt
+    ```
+* Install the local project as a package - go to the project root folder and run
+    ```bash
+      pip install .
+    ```
+* Verify the package was installed successfully:
+  ```bash
+    pip list || grep dbt-clickhouse
+    ```
+  the package will be directed to your local project.
+
+### 3. Create a Branch
+
+Create a new branch for your feature or bug fix, please make sure to follow 
+
+```bash
+git checkout -b my-new-feature
+```
+
+### 4. Make Your Changes
+
+Make the necessary changes in your branch. Ensure that your code follows the existing style and conventions used in the
+project.
+We strongly recommend to stick to [this](https://www.conventionalcommits.org/en/v1.0.0/) official commit message conventions.
+
+### 5. Add or Adjust Tests
+
+The project tests are located under the `test` folder. Please look for the relevant test associated with
+your changes, and adjust it. If not such test, please create one.
+
+### 6. Run The Tests
+
+See [Running Tests](#running-tests) for more information.
+
+> **Important:** Please make sure the tests are running successfully before pushing your code.
+
+### 7. Create a PR
+Create a pull request from your forked repository to the main one, include the following:
+* In case this is your first contribution, make sure to sign ClickHouse's CLA.
+* Link the related issue to your PR.
+* Add a sensible description of the feature/issue and detail the use case.
+* Make sure to update [CHANGELOG.md](CHANGELOG.md).
+
+
+# Running Tests
+
+This adapter passes all of dbt basic tests as presented in dbt's [official docs](https://docs.getdbt.com/docs/contributing/testing-a-new-adapter#testing-your-adapter).
+Use `pytest tests` to run tests.
+
+You can customize the test environment via environment variables. We recommend doing so with the pytest `pytest-dotenv` plugin combined with root level `test.env`
+configuration file (this file should not be checked into git).  The following environment variables are recognized:
+
+1. DBT_CH_TEST_HOST - Default=`localhost`
+2. DBT_CH_TEST_USER - your ClickHouse username. Default=`default`
+3. DBT_CH_TEST_PASSWORD - your ClickHouse password. Default=''
+4. DBT_CH_TEST_PORT - ClickHouse client port. Default=8123 (The default is automatically changed to the correct port if DBT_CH_TEST_USE_DOCKER is enabled)
+5. DBT_CH_TEST_DB_ENGINE - Database engine used to create schemas.  Defaults to '' (server default)
+6. DBT_CH_TEST_USE_DOCKER - Set to True to run clickhouse-server docker image (see tests/docker-compose.yml).  Requires docker-compose. Default=False
+7. DBT_CH_TEST_CH_VERSION - ClickHouse docker image to use.  Defaults to `latest`
+8. DBT_CH_TEST_INCLUDE_S3 - Include S3 tests.  Default=False since these are currently dependent on a specific ClickHouse S3 bucket/test dataset
+9. DBT_CH_TEST_CLUSTER_MODE - Use the profile value
+10. DBT_CH_TEST_CLUSTER - ClickHouse cluster name, if DBT_CH_TEST_USE_DOCKER set to true, only `test_replica` and `test_shard` is valid (see tests/test_config.xml for cluster settings)

README.md

@@ -349,25 +349,10 @@ CREATE TABLE db.table on cluster cluster
 ENGINE = Distributed('cluster', 'db', 'table_local', cityHash64(id));
 ```
 
-# Running Tests
-
-This adapter passes all of dbt basic tests as presented in dbt's official docs: https://docs.getdbt.com/docs/contributing/testing-a-new-adapter#testing-your-adapter.
-Use `pytest tests` to run tests.
-
-You can customize the test environment via environment variables. We recommend doing so with the pytest `pytest-dotenv` plugin combined with root level `test.env`
-configuration file (this file should not be checked into git).  The following environment variables are recognized:
-
-1. DBT_CH_TEST_HOST - Default=`localhost`
-2. DBT_CH_TEST_USER - your ClickHouse username. Default=`default`
-3. DBT_CH_TEST_PASSWORD - your ClickHouse password. Default=''
-4. DBT_CH_TEST_PORT - ClickHouse client port. Default=8123 (The default is automatically changed to the correct port if DBT_CH_TEST_USE_DOCKER is enabled)
-6. DBT_CH_TEST_DB_ENGINE - Database engine used to create schemas.  Defaults to '' (server default)
-7. DBT_CH_TEST_USE_DOCKER - Set to True to run clickhouse-server docker image (see tests/docker-compose.yml).  Requires docker-compose. Default=False
-8. DBT_CH_TEST_CH_VERSION - ClickHouse docker image to use.  Defaults to `latest`
-9. DBT_CH_TEST_INCLUDE_S3 - Include S3 tests.  Default=False since these are currently dependent on a specific ClickHouse S3 bucket/test dataset
-10. DBT_CH_TEST_CLUSTER_MODE - Use the profile value
-11. DBT_CH_TEST_CLUSTER - ClickHouse cluster name, if DBT_CH_TEST_USE_DOCKER set to true, only `test_replica` and `test_shard` is valid (see tests/test_config.xml for cluster settings)
+## Contributing
+We welcome contributions from the community to help improve the dbt-ClickHouse adapter. Whether you’re fixing a bug, adding a new feature, or enhancing documentation, your efforts are greatly appreciated!
 
+Please take a moment to read our [Contribution Guide](CONTRIBUTING.md) to get started. The guide provides detailed instructions on setting up your environment, running tests, and submitting pull requests.
 
 ## Original Author
 ClickHouse wants to thank @[silentsokolov](https://github.com/silentsokolov) for creating this connector and for their valuable contributions.