---
name: contribute-dlt-connector
description: Push local dlt connector changes back to the central monorepo via pull request. Use when the user wants to contribute a fix upstream, open a PR against the monorepo, push connector changes back, or submit improvements from a client Airflow repo to dlt-connectors.
disable-model-invocation: true
---

# Contribute Connector Changes

Push local connector fixes or enhancements from a client Airflow repo back to the central dlt-connectors monorepo via a pull request.

## Context

When connectors are synced into a client Airflow repo (via `sync-connectors.sh`), developers may fix bugs or add features locally. These changes need to flow back to the monorepo so all clients benefit. The `contribute-connector.sh` script automates this: it clones the monorepo, copies the local changes, creates a branch, and opens a PR.

### Prerequisites

- `git` and `gh` (GitHub CLI, authenticated) installed
- `contribute-connector.sh` present in the repo root (copied during sync-connectors setup)
- `connectors.lock.yml` present in the repo root
- The connector directory exists locally at `connectors/<name>/`

## Important: Connectors Are Not Git-Tracked

The `connectors/` directory is listed in `.gitignore` because it is synced from the monorepo via `sync-connectors.sh`. This means:

- `git status`, `git diff`, and similar commands will **never show changes** to connector files.
- To check whether a connector has local modifications, compare it against the monorepo directly. The easiest way is to run the contribute script — it clones the monorepo and reports a diff. If there are no differences, it exits with "No changes detected."
- You can also manually diff against the monorepo version pinned in `connectors.lock.yml`.

## Workflow

### 1. Identify which connector has changes

Since connectors are gitignored, ask the user which connector was modified and what was changed. If unsure, run the contribute script in dry-run fashion — it will show a `git diff --stat` before pushing.

### 2. Make changes to the connector

Edit the connector code in `connectors/<name>/`. This is the local copy synced from the monorepo.

### 3. Test locally

Run the connector inside the Airflow environment to verify your changes work:

```bash
cd connectors/<name>
uv sync
uv run python <name>_pipeline.py
```

Or if running within the Airflow container, use however the project normally executes DAGs/tasks.

### 4. Contribute back to the monorepo

Run the contribute script from the repo root:

```bash
./contribute-connector.sh <name> "<description of changes>"
```

Example:

```bash
./contribute-connector.sh google_ads "fix pagination for v2 API"
```

This will:
- Clone the dlt-connectors monorepo to a temp directory
- Copy your local connector files (excluding `.venv/`, `__pycache__/`, secrets)
- Show a diff of what changed compared to the monorepo's `main` branch
- If there are no differences, exit early with "No changes detected"
- Otherwise, create a branch `fix/<name>-<description-slug>`
- Commit with message `fix(<name>): <description>`
- Push and open a PR via `gh`

### 5. Commit message conventions

The commit message prefix determines how the version is bumped when the PR is merged:

| Prefix | Version Bump | Example |
|--------|-------------|---------|
| `fix(<name>):` | Patch (v0.1.0 → v0.1.1) | Bug fixes, minor adjustments |
| `feat(<name>):` | Minor (v0.1.1 → v0.2.0) | New features, new endpoints |
| `BREAKING CHANGE` in body | Major (v0.2.0 → v1.0.0) | Schema changes, removed fields |

The `contribute-connector.sh` script defaults to `fix()` prefix. If your change is a new feature, edit the PR title/commit to use `feat(<name>):` before merging.

### 6. Wait for merge

The PR is reviewed and merged in the monorepo. On merge to `main`, the `auto-tag.yml` GitHub Action automatically:
- Detects which connectors changed
- Creates a new version tag (e.g., `google_ads/v0.1.2`)

Note: The `version` field in `pyproject.toml` is informational only and may not match the latest tag. The git tag is the canonical version.

### 7. Update the lock and re-sync

After the PR is merged and auto-tagged, update your client repo to pull in the new version:

1. Check the new tag in the monorepo (or look at the auto-tag workflow run)
2. Update `connectors.lock.yml` with the new version:

```yaml
connectors:
  google_ads:
    version: "google_ads/v0.1.2"  # Updated from v0.1.1
```

3. Re-sync:

```bash
./sync-connectors.sh
```

4. Commit the updated lock file and synced connector.

## Validation

- [ ] Connector tested locally before contributing
- [ ] `contribute-connector.sh` ran and showed the diff
- [ ] PR opened in the monorepo (check with `gh pr list` in the temp clone)
- [ ] Commit message uses correct prefix (`fix()` for patches, `feat()` for new features)
- [ ] After merge: `connectors.lock.yml` updated with new version tag
- [ ] After merge: `sync-connectors.sh` re-run to pull the merged version

## Reference

- `contribute-connector.sh` — The script that handles cloning, copying, branching, and PR creation
- `sync-connectors.sh` — Re-syncs connectors from the monorepo after version updates
- `connectors.lock.yml` — Pins each connector to a specific version tag
- `.github/workflows/auto-tag.yml` (in the monorepo) — Automatically creates version tags on merge