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.
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.mdandlog.md(§3, §6, §7), but both names miss conventions that are already universal in the git ecosystem.README.mdis 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.mdevokes web-server directory listings — it has no equivalent meaning in git tooling.CHANGELOG.mdis the standard for chronological change history and works at any directory scope, not just the repo root.log.mdhas 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:
index.mdREADME.mdlog.mdCHANGELOG.mdRecognize both names during a transition window, then deprecate the old names in the next minor version.
Acceptance Criteria
CHANGELOG.mdis immediately recognizable without consulting OKF docs.index.md/log.md, when the spec transitions, a migration path or dual-recognition window is documented.