GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Rename reserved files: `index.md` → `README.md`, `log.md` → `CHANGELOG.md`

Open
#146 0 comments 8 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.