Merge pull request #1879 from weaviate/docs/update-repo-guides

Docs - update repo docs for tests & release creation

Author: dirkkul

CONTRIBUTING.md

@@ -1,18 +1,12 @@
 ### Setup
 
-We recommend that you use a virtual environment to contribute to the client.
-
-To create a virtual environment, activate it, and install dependencies, run the following shell code:
+The development requirements are listed in the `requirements-devel.txt` file. Install them to your virtual environment with:
 
 ```shell
-python3 -m venv .venv
-source .venv/bin/activate
 pip install -r requirements-devel.txt
 ```
 
-To activate your virtual environment, run `source .venv/bin/activate`.
-
-The newest client versions sometimes require upcoming Weaviate core features. We recommend using Docker (see https://weaviate.io/developers/weaviate/installation/docker-compose) to run a local instance of the `latest Weaviate core <https://hub.docker.com/r/semitechnologies/weaviate/tags>`_ for client development.
+The newest client versions sometimes require upcoming Weaviate core features. We recommend using Docker (see https://docs.weaviate.io/deploy/installation-guides/docker-installation) to run a local instance of the `latest Weaviate core <https://hub.docker.com/r/semitechnologies/weaviate/tags>`_ for client development.
 
 #### Installation
 
@@ -34,10 +28,16 @@ You can install a particular branch directly from GitHub with:
 pip install git+https://github.com/weaviate/weaviate-python-client.git@BRANCH_NAME
 ```
 
+If any static analysis tools such as Pylance fail, try installing the package with:
+`--config-settings editable_mode=compat` suffix. (e.g. `pip install -e . --config-settings editable_mode=compat`)
 
 ### Testing
 
-> Note: We use [pytest](https://docs.pytest.org) to write tests for new client code. However, many older tests use [unittest](https://docs.python.org/3/library/unittest.html). These commands run the `pytest` and `unittest` tests.
+To set up the testing environment, install the test requirements with:
+
+```shell
+pip install -r requirements-test.txt
+```
 
 There are three kinds of tests:
 - Unit tests test individual client components.
@@ -67,9 +67,10 @@ pytest test
 > We strongly recommend using [pre-commit](https://pre-commit.com/) to automatically run all linters locally on each commit. Install `pre-commit` on your system, and then enable it with `pre-commit install`.
 
 We use the following tools to ensure a high code quality:
-- black (formatter), run with `black $FOLDER_WITH_CHANGES`
-- flake8 with plugins. Run with `flake8 $FOLDER_WITH_CHANGES`. Note that all plugins are listed in the `requirements.txt` file and are installed in the first step.
+- ruff (formatter), run with `ruff format $FOLDER_WITH_CHANGES`
+- flake8 with plugins. Run with `flake8 $FOLDER_WITH_CHANGES`.
 
+Note that all plugins are listed in the `requirements-devel.txt` file and are installed in the first step.
 
 ### Creating a Pull Request
 

RELEASING.md

@@ -0,0 +1,30 @@
+## How to create releases
+
+### Step 1: Prepare for release
+1. Pull latest main
+	- Merge any pending PRs
+2. Determine what the next version should be, following semantic versioning
+3. Create a new branch for the changelog
+4. Add a changelog entry to `docs/changelog.rst`
+	- `gh pr list --repo weaviate/weaviate-python-client --state merged --search "merged:>=YYYY-MM-DD"` where `YYYY-MM-DD` is the last release date
+	- Only add the relevant entries to the changelog
+	- Examples - [minor release](https://github.com/weaviate/weaviate-python-client/releases/tag/v4.18.0), [patch release](https://github.com/weaviate/weaviate-python-client/releases/tag/v4.16.10)
+5. Merge back to main
+6. Pull main
+
+### Step 2: Create release
+Option 1: With GH CLI
+1. `gh release create <VERSION_TAG>` (e.g. `gh release create v4.18.1`)
+
+Option 2: With git + GH web UI
+1. git tag VERSION
+	- `git tag -a v4.18.1 -m "v4.18.1"
+2. `git push --tags`
+3. Create a release [from the GH repo](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository?tool=webui#creating-a-release)
+
+### Step 3: Monitor pipeline
+1. Monitor the CICD pipeline
+	1. When all tests pass, the release will be pushed to PyPI automatically
+
+### Notes:
+- The package version is updated automatically (see setup.cfg)

publishing.md

@@ -1,64 +1 @@
-# Unit tests for Weaviate Python client
----
-Unit tests for weaviate package. Each module should have its own sub-directory in the `test` directory. Each test file should begin with `test_<fine_name>.py` and `test` directory should not be renamed, these are mandatory requirements for the `unittest` to parse and run all unittests.
-
-The `util.py` contains helper functions for unit testing.
-
----
-## Run one file unittest
-In order to unit test a single file, you can run the following command:
-```
-python -m unittest path_to_file_dir.file
-```
-E.g. if you run it from repo root folder:
-```bash
-python -m unittest test.gql.test_get -v # -v is optional, -v = verbose
-```
-## Run whole package unittest
-In order to unit test the whole package, you can run the following command:
-```bash
-python -m unittest -v # -v is optional, -v = verbose
-```
-
-# Coverage test
----
-Coverage test for weaviate package. Coverage test can be performed using the existing unit test. It runs all the unit tests in order to find which parts of the code have been executed, thus it can be used instead of the Unit test.
-Coverage test is performed by the `coverage` package that should be installed with the `development-requirements.txt`. For more information on what and how to run coverage tests visit this [link](https://coverage.readthedocs.io/en/coverage-5.3.1/ "coverage.readthedocs.io").
-
----
-
-## Run coverage test for one file
-Coverage test for one file can be performed using the following command:
-```bash
-coverage run -m unittest path_to_the_file_dir.file -v # -v is optional, -v = verbose
-```
-E.g. if you run it from repo root folder:
-```bash
-coverage run -m unittest test.gql.test_get -v # -v is optional, -v = verbose
-```
-
-## Run whole package coverage test
-In order to unit test the whole package, you can run the following command:
-```bash
-coverage run -m unittest -v # -v is optional, -v = verbose
-```
-## Show coverage report
-To get the coverage report run the following command.
-```bash
-coverage report -m --skip-covered # --skip-covered = skip 100% covered files, -m = show missing lines
-```
-
-# Linting
----
-Lint the files that are modified before commiting. The linting is done by `pylint`.
-
-To lint a file/module/package run the following command:
-```bash
-pylint path_to_the_file_or_module
-```
-E.g. if you run it from repo root folder:
-```bash
-pylint weaviate # for the whole package
-pylint weaviate/batch # for the module batch
-pylint weaviate/connect/connection.py # for the connection.py file
-```
+Refer to [CONTRIBUTING.md](CONTRIBUTING.md) file for instructions on how to run the tests.