# Release and Build Guide for cognite-data-quality

This document describes how to build the `cognite-data-quality` package, publish to PyPI, and how the thisisneat dependency is handled.

## PyPI publishing (CD workflow)

The repository uses a release workflow aligned with [cognite-databricks](https://github.com/cognitedata/cognite-databricks).

### Prerequisites

1. **GitHub environment `CD`**: Create an environment named `CD` in the repository settings (Settings → Environments).
2. **PyPI API token**: Add `PYPI_API_TOKEN` as a secret in the `CD` environment. Create a token at [PyPI Account Settings → API tokens](https://pypi.org/manage/account/token/).

### Release flow

1. Create a release branch (e.g. `release/0.1.0`).
2. Make a small change (e.g. README typo).
3. Create a PR with a body that includes:
   - `## Bump` section with exactly one checked option: `[x] Patch`, `[x] Minor`, or `[x] Major`
   - `## Changelog` section with headers like `### Added`, `### Fixed`, etc., each followed by a list of changes
   - Never put any smileys in the PR text, that will fail the release.
4. Merge via "Create a merge commit" and **edit the merge commit message** to include the full `## Bump` and `## Changelog` sections (the workflow reads the merge commit message).
5. The workflow runs on push to `main`, bumps the version from the last tag, builds, uploads to PyPI, and creates a GitHub release.

### Initial release

Before the first release, create an initial tag so `git describe --tags --abbrev=0` succeeds:

```bash
git tag v0.0.0
git push origin v0.0.0
```

### Version files

Keep `pyproject.toml`, `cognite_data_quality/_version.py`, and `cognite_data_quality/_function_code/requirements.txt` at `0.0.0` in the repository. The workflow bumps them all during the release run via `dev.py bump`.

---

## Building the wheel

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Build steps (per release process)

From the **data-quality-validation** directory:

```bash
# Install dependencies (using uv)
uv sync --all-extras

# Run linting
uv run pre-commit run --all-files

# Run tests
uv run pytest

# Build the package (wheel and sdist)
uv build
```

The built wheel and source distribution are written to `dist/`:

- `dist/cognite_data_quality-<version>-py3-none-any.whl`
- `dist/cognite_data_quality-<version>.tar.gz`

### Version for local builds

Local builds use version **0.0.0** for development and testing. Published releases use semantic versions (e.g. 0.0.2, 0.1.0).

### thisisneat dependency (CDF SPARQL extensions)

The package depends on thisisneat, which is published to PyPI:

- **PyPI package:**
  https://pypi.org/project/thisisneat/

- **Dependency declaration:**
  `thisisneat==0.2.6`

- **Implications:**
  - The package is now fully self-contained and can be installed directly from PyPI.
  - No special build environment configuration is required.

### Installing the built wheel

```powershell
pip install "path\to\data-quality-validation\dist\cognite_data_quality-0.0.0-py3-none-any.whl"
```

Or with uv:

```bash
uv pip install dist/cognite_data_quality-0.0.0-py3-none-any.whl
```

After installation, `import cognite_data_quality` and `run_validation` use thisisneat from PyPI.

## Deploying functions (local wheel)

When deploying Cognite Functions and cognite-data-quality is not on PyPI, the deployment process automatically builds the wheel locally and bundles it in the function zip. The function code is located in `cognite_data_quality/_function_code/`.

The deployment flow handles all packaging automatically - no manual wheel copying is needed.

Example:

```python
from cognite_data_quality import deploy_validation_infrastructure, load_cognite_client_from_toml
from cognite_data_quality.deploy import ShaclRulesRef

deploy_validation_infrastructure(
    client=client,
    settings_path="config/environments/cog-sail/settings.yaml",
    data_models=[("sailboat", "sailboat", "v1")],
    default_shacl_rules=ShaclRulesRef(file="sailboat_data_quality_rules.ttl", external_id="..."),
    function_source_root=".",
    debug_deploy=True,
    debug_save_zip="dist/debug-zips",
)
```
