# Contributing

> CLA requirements, fork-and-PR workflow, style expectations, and test commands for Python pytest and TypeScript npm run test across package directories.

- Repository: GoogleCloudPlatform/knowledge-catalog
- GitHub: https://github.com/GoogleCloudPlatform/knowledge-catalog
- Human docs: https://grok-wiki.com/public/docs/googlecloudplatform-knowledge-catalog-9cee6ee3cba5
- Complete Markdown: https://grok-wiki.com/public/docs/googlecloudplatform-knowledge-catalog-9cee6ee3cba5/llms-full.txt

## Source Files

- `CONTRIBUTING.md`
- `CODE_OF_CONDUCT.md`
- `LICENSE.md`
- `okf/pyproject.toml`
- `agents/mdcode/package.json`
- `okf/README.md`

---

---
title: "Contributing"
description: "CLA requirements, fork-and-PR workflow, style expectations, and test commands for Python pytest and TypeScript npm run test across package directories."
---

Contributions to Google Cloud Knowledge Catalog land through GitHub pull requests against `GoogleCloudPlatform/knowledge-catalog`. The repository ships under the Apache 2.0 license; every submission must be covered by a Google Contributor License Agreement (CLA), match the style of the package you touch, and pass that package's automated tests before review.

## License and community standards

All solutions in this repository are distributed under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license. See `LICENSE.md` at the repository root for full terms.

Participation is governed by `CODE_OF_CONDUCT.md`, adapted from the Contributor Covenant. Reports go to `@googleapis/senseai-eco` or, if needed, `opensource@google.com`.

## Contributor License Agreement

Contributions must be accompanied by a Contributor License Agreement. You (or your employer) retain copyright; the CLA grants Google permission to use and redistribute your work as part of the project.

<Steps>
<Step title="Check or sign the CLA">

Visit [https://cla.developers.google.com/](https://cla.developers.google.com/) to view existing agreements or sign a new one.

</Step>
<Step title="Confirm CLA status on your PR">

You generally sign the CLA once across Google open-source projects. If you have signed before for another project, you usually do not need to sign again.

</Step>
</Steps>

<Note>
Corporate contributors may need an authorized representative to sign the CLA on behalf of their employer.
</Note>

## Fork-and-PR workflow

All submissions — including those from maintainers — go through GitHub pull requests.

<Steps>
<Step title="Fork and clone">

Fork [GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog) on GitHub, then clone your fork locally.

</Step>
<Step title="Create a feature branch">

Make changes on a branch off `main`. Scope each PR to a focused set of changes in one or more related packages.

</Step>
<Step title="Develop and test locally">

Install dependencies for the packages you modify and run their test commands (see tables below). Add or update unit tests when you change behavior.

</Step>
<Step title="Match existing style">

Keep formatting, naming, and patterns consistent with the surrounding code in each package directory.

</Step>
<Step title="Open a pull request">

Push your branch and open a PR against `main`. Address review feedback; maintainers use GitHub PR review for all merges.

</Step>
</Steps>

<Tip>
See [GitHub Help — About pull requests](https://help.github.com/articles/about-pull-requests/) for general PR mechanics.
</Tip>

## Repository layout

The monorepo groups independent packages. Touch the directory that owns the surface you are changing.

:::files
knowledge-catalog/
├── okf/                      # OKF enrichment agent (Python, pytest)
├── agents/
│   ├── mdcode/               # kcmd Metadata as Code CLI + library (TypeScript)
│   └── enrichment/           # Catalog enrichment agent (Python, eval tooling)
├── toolbox/
│   ├── mdcode/               # kcmd copy for toolbox consumers (TypeScript)
│   └── enrichment/           # kcagent TypeScript enrichment harness
└── samples/                  # Discovery and demo samples
:::

| Package path | Language | Primary artifact | Automated test entry point |
|---|---|---|---|
| `okf/` | Python ≥ 3.11 | `enrichment-agent` CLI, OKF bundles | `pytest` |
| `agents/mdcode/` | TypeScript (Bun test runner) | `kcmd` CLI, MCP server | `npm run test` |
| `toolbox/mdcode/` | TypeScript (Bun test runner) | `kcmd` CLI (toolbox layout) | `npm run test` |
| `toolbox/enrichment/` | TypeScript | `kcagent`, `md-fileset` | `npm run compile` (no `test` script) |
| `agents/enrichment/` | Python | `agent_runner.py` enrichment modes | No pytest suite; optional `python -m eval` |

<Info>
`agents/mdcode/` and `toolbox/mdcode/` are parallel copies of the kcmd package. Run tests in whichever tree you modify.
</Info>

## Style expectations

`CONTRIBUTING.md` requires that code **adheres to the existing style** in each package. The repository does not ship a root-level formatter or linter configuration; follow the conventions already present in the directory you edit.

### TypeScript (`agents/mdcode`, `toolbox/mdcode`, `toolbox/enrichment`)

TypeScript packages use `strict` compiler mode. The root `tsconfig.json` in `agents/mdcode` additionally enables `noUnusedLocals`, `noImplicitReturns`, and `noFallthroughCasesInSwitch`.

| Check | Command | When to run |
|---|---|---|
| Typecheck | `npm run compile` | Before every PR that touches TypeScript |
| Build | `npm run build` | When you change CLI entrypoints or compiled artifacts |
| Unit tests | `npm run test` | Required for `agents/mdcode` and `toolbox/mdcode` changes |

Match import style (`nodenext` modules), naming, and error-handling patterns in neighboring files. Scenario tests live under `tests/libts/scenarios.ts` and load YAML fixtures from `tests/scenarios/`.

### Python (`okf/`, `agents/enrichment/`)

The `okf` package declares `requires-python = ">=3.11"` and ships pytest configuration in `pyproject.toml` (`testpaths = ["tests"]`, `pythonpath = ["src"]`).

Python under `agents/enrichment/` follows Google-style patterns visible in source (for example, targeted `pylint: disable` comments for broad exceptions and import placement). Match indentation, docstring tone, and module layout in `src/` and `eval/`.

For OKF document content produced by agents, the enrichment prompt in `okf/src/enrichment_agent/prompts/enrichment_instruction.md` defines style rules: be concrete, do not invent metadata fields, and write valid markdown without preamble or reasoning narration.

## Running tests

### Python: `okf/` (pytest)

The OKF enrichment agent is the only Python package with a formal pytest suite. Seven test modules cover bundle tools, document parsing, indexing, BigQuery source behavior, web fetchers, and the visualization pipeline.

<Tabs>
<Tab title="Setup">

```bash
cd okf
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
```

The `[dev]` extra installs `pytest>=7.0`.

</Tab>
<Tab title="Run all tests">

```bash
.venv/bin/pytest
```

</Tab>
<Tab title="Run a single module">

```bash
.venv/bin/pytest tests/test_document.py -v
```

</Tab>
</Tabs>

<Check>
A clean run reports all tests passed (currently 33 tests across the `okf/tests/` tree).
</Check>

### TypeScript: `agents/mdcode` and `toolbox/mdcode`

Both packages expose identical npm scripts. Tests are **Bun scenario tests** that replay YAML-defined init/pull/push workflows against in-memory mocks — no live GCP calls.

<CodeGroup>

```bash title="agents/mdcode"
cd agents/mdcode
npm install
npm run build    # optional but recommended before test
npm run test
```

```bash title="toolbox/mdcode"
cd toolbox/mdcode
npm install
npm run build
npm run test
```

</CodeGroup>

`npm run test` delegates to `npm run test:libts`, which executes:

```bash
npx bun test ./tests/libts/scenarios.ts
```

#### Run a subset of scenarios

Set `TEST_GLOB` to filter YAML scenario files under `tests/scenarios/`:

```bash
TEST_GLOB='pull_bq*.yaml' npm run test
```

Scenario files cover manifest initialization, pull/push sync for BigQuery datasets, knowledge bases, entry groups, BigLake namespaces, reference layers, entry links, and custom entries.

### TypeScript: `toolbox/enrichment`

The `toolbox/enrichment` package builds `kcagent` and `md-fileset` binaries. Its `package.json` defines `build`, `compile`, and `debug` scripts but **does not define a `test` script**, even though `toolbox/enrichment/README.md` mentions `npm run test`.

<Warning>
For `toolbox/enrichment` changes, run `npm run compile` for type safety and `npm run build` to verify compilation. Do not expect `npm run test` to succeed until a test script is added to `package.json`.
</Warning>

```bash
cd toolbox/enrichment
npm install
npm run compile
npm run build
```

### Python: `agents/enrichment/` (no pytest suite)

`agents/enrichment/` has no checked-in pytest tests. Validation for enrichment output is handled by the optional eval CLI under `agents/enrichment/eval/`, which scores runs via `python -m eval` rather than unit tests.

```bash
cd agents/enrichment
pip install -r src/requirements.txt
pip install -r eval/requirements.txt

# Score an existing enrichment output directory:
python -m eval --output-dir /path/to/enrich_out
```

Use eval when you change enrichment behavior and need quality signals; it is not a substitute for the pytest or `npm run test` gates required by `CONTRIBUTING.md` in other packages.

## Pre-submission checklist

| Requirement | Verification |
|---|---|
| CLA signed | [cla.developers.google.com](https://cla.developers.google.com/) |
| Apache 2.0 compatibility | Contributions inherit repo license terms |
| Style consistency | Matches surrounding code; `npm run compile` clean for TS |
| Unit tests for behavior changes | New or updated tests in the affected package |
| All package tests pass | `pytest` in `okf/`; `npm run test` in mdcode dirs you touched |
| PR opened against `main` | GitHub pull request with review |

<AccordionGroup>
<Accordion title="What reviewers expect">

Reviewers check that changes are scoped, tested, and consistent with package conventions. TypeScript PRs should not introduce `tsc --noEmit` errors under `npm run compile`. Python PRs touching `okf/` should keep the pytest suite green.

</Accordion>
<Accordion title="When you change multiple packages">

Run tests in every package directory you modify. A change spanning `okf/` and `agents/mdcode/` requires both `pytest` and `npm run test` in their respective roots.

</Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Prerequisites, Python and Node.js setup, and credential configuration before you run package tests locally.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Auth, billing, and test-environment failures that block local verification.
</Card>
<Card title="Overview" href="/overview">
Knowledge Catalog tooling surface and how the packages under `agents/`, `okf/`, and `toolbox/` fit together.
</Card>
</CardGroup>