GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: give OKF its own first-class repository

Open
#43 0 comments 15 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

OKF currently lives as the `okf/` subdirectory of `GoogleCloudPlatform/knowledge-catalog`, alongside `agents/`, `samples/`, and `toolbox/`. The repo's stated purpose is "tools, agents, and samples that demonstrate Knowledge Catalog features." That's a fine home for demos — but OKF is a different *kind* of thing (a portable format/spec meant to be adopted across tools and vendors), and I think it would be better served by its own first-class repository.

**Why it matters:**

- **Scoped issues and PRs.** OKF needs to evolve, and its issue tracker and pull requests should be *about OKF* — not interleaved with Knowledge Catalog tooling, sample code, and the toolbox. A contributor filing an OKF spec question shouldn't have to disambiguate it from the surrounding product demos, and maintainers triaging OKF shouldn't have to filter it out of an unrelated backlog.
- **Independent versioning and releases.** The spec is explicitly v0.1 Draft and meant to grow through versioned, backward-compatible evolution. A spec wants its own tags, changelog, and release cadence — hard to do cleanly when it shares a repo (and release history) with several unrelated components.
- **Adoption optics.** OKF's whole pitch is "a format, not a platform… vendor-neutral… the lingua franca knowledge can be exchanged for." That argument lands better from a standalone repo than from a subdirectory of a single cloud vendor's demo repository. A first-class repo reduces the perceived "is this just a GCP thing?" friction that the format's own positioning works to dispel.
- **A clear home for a spec.** Its own `README`, `SPEC.md`, conformance notes, examples, `CODEOWNERS`, and versioned history — discoverable, linkable, and citable as *the* OKF repo.

**Suggested shape (maintainers' call entirely):**

- Extract `okf/` into its own repository (e.g. `GoogleCloudPlatform/okf`, or an org-neutral home if that fits the vendor-neutral framing), preserving git history (`git filter-repo`/subtree).
- Leave a short pointer at `knowledge-catalog/okf/README.md` redirecting to the new repo.
- Keep the Knowledge Catalog agents/samples referencing OKF as a dependency, so the demos still work.

Happy to help with the mechanics (history-preserving extraction, the redirect pointer) if that's useful. Either way — thanks for publishing OKF; it's exactly the small, portable thing this space needed.

---
*Drafted by AI (Claude Code, Opus 4.8) under the direction of Peter Kaminski, who has reviewed it and takes full responsibility for its content.*

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.