GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Rename reserved files: `index.md` → `README.md`, `log.md` → `CHANGELOG.md`
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
As a developer hosting an OKF bundle in a git repository, I want the reserved filenames to follow established git conventions so that I get free directory rendering and familiar semantics without extra work.
## Problem Statement
OKF reserves `index.md` and `log.md` (§3, §6, §7), but both names miss conventions that are already universal in the git ecosystem.
`README.md` is auto-rendered by GitHub, GitLab, and Gitea at every directory level.
An OKF bundle hosted on any of these platforms would get a free, human-readable index with no configuration. `index.md` evokes web-server directory listings — it has no equivalent meaning in git tooling.
`CHANGELOG.md` is the standard for chronological change history and works at any directory scope, not just the repo root. `log.md` has no established meaning anywhere in the git world.
Neither name has a documented rationale in the v0.1 spec.
## Proposed Solution
Replace the reserved filenames:
| Current | Proposed |
|---|---|
| `index.md` | `README.md` |
| `log.md` | `CHANGELOG.md` |
Recognize both names during a transition window, then deprecate the old names in the next minor version.
## Acceptance Criteria
- Given an OKF bundle hosted on GitHub, when a user browses any subdirectory, then the directory index renders automatically without extra configuration.
- Given a contributor familiar with git conventions, when they look for the change history of a subdirectory, `CHANGELOG.md` is immediately recognizable without consulting OKF docs.
- Given an existing bundle using `index.md` / `log.md`, when the spec transitions, a migration path or dual-recognition window is documented.
Contributor guide
Research direction
Read the v0.1 spec sections 3, 6, and 7, which define the reserved filenames and their current semantics. Trace where those rules are documented, then confirm that the proposed names, transition handling, and migration path are specified clearly enough to satisfy the three acceptance scenarios.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100