Skip to content

Rename reserved files: index.mdREADME.md, log.mdCHANGELOG.md #146

Description

@olegshulyakov

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions