Skip to content

fix(docs): OKF conformance of developer-docs + CI validation - #1445

Open
galkleinman wants to merge 2 commits into
firebase:mainfrom
galkleinman:fix/okf-bundle-root-index-frontmatter
Open

fix(docs): OKF conformance of developer-docs + CI validation#1445
galkleinman wants to merge 2 commits into
firebase:mainfrom
galkleinman:fix/okf-bundle-root-index-frontmatter

Conversation

@galkleinman

Copy link
Copy Markdown

developer-docs/ does not currently pass OKF v0.1 conformance, so tooling that reads the bundle rejects it before reading any of the content.

What fails

Every key on the bundle-root index.md except okf_version. §8 is explicit that index files carry no frontmatter, with exactly one exception — a bundle-root index.md may declare okf_version (§12) — and §11.3 makes the reserved-filename structure a conformance requirement:

developer-docs/index.md
  2  error  `index.md` must not carry frontmatter key `type`
  3  error  `index.md` must not carry frontmatter key `title`
  4  error  `index.md` must not carry frontmatter key `description`
  5  error  `index.md` must not carry frontmatter key `tags`
  7  error  `index.md` must not carry frontmatter key `timestamp`

Nothing is lost by removing them. The body's # developer-docs heading and opening line already carry the title and description, and an index file is not a concept document, so type, tags, and timestamp have no defined meaning on one. The rest of the bundle is already conformant — this is the only file that fails.

This matches developer-docs/documentation-policy.md, which requires frontmatter with a type on concept files and says nothing about index files.

CI

Adds .github/workflows/developer-docs.yaml, running conformance only (§11: parseable frontmatter, non-empty type, reserved-file structure). §11 forbids consumers from rejecting a bundle for broken cross-links, unknown type values, unknown keys, or missing optional fields, so this gate cannot fail on any of those — it catches the structural breakage above and nothing else. The bundle is also clean of advisory warnings today, if you would rather run command: lint instead.

Path-scoped so it runs only when developer-docs/ changes, action pinned by SHA and permissions: contents: read, matching lint.yaml.

The action is okf-toolkit, Apache-2.0. Happy to swap it for a plain curl-and-run step, or to drop the CI commit entirely and keep just the fix, whichever you prefer.

OKF §8 allows no frontmatter on an index.md, with one exception: a
bundle-root index.md may carry okf_version (§12). The five other keys
here make developer-docs/ fail §11.3 conformance.

Nothing is lost: the body's `# developer-docs` heading and opening line
already carry the title and description, and index files are not concept
documents, so type/tags/timestamp have no defined meaning on one.
@google-cla

google-cla Bot commented Aug 12, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request simplifies the frontmatter of the developer-docs/index.md file by removing several metadata fields, including type, title, description, tags, and timestamp, while retaining the okf_version field. There are no review comments, and I have no feedback to provide.

Conformance only (§11): parseable frontmatter, a non-empty type, and the
reserved index.md/log.md structure. §11 forbids consumers rejecting a
bundle for broken links or missing optional fields, so this cannot fail
on those. Scoped by path so it runs only when the bundle changes.
@galkleinman
galkleinman force-pushed the fix/okf-bundle-root-index-frontmatter branch from 3a68996 to d1b1e4a Compare August 12, 2026 19:59
@galkleinman galkleinman changed the title Fix OKF conformance of developer-docs/ and validate it in CI fix(docs): OKF conformance of developer-docs + CI validation Aug 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant