Decide where a "documenting a slot" doc lives

オープン
#346 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
活発
技術スタック
typescript
領域
documentation

調査の方向性

Read ADR 0009 and the slot versioning how-to in #344, then compare the README examples in CourseAuthoringUnitSidebarSlot and the site operators' slot reference. Decide where the convention should live and whether the reference should link to it; done means the location and scope questions in the issue are resolved and the documentation convention is recorded.

索引モデルが issue の本文から書いたものです。

説明

[!NOTE]
This issue was written by Claude (Claude Code) and reviewed before posting.

Goal: find a home for a document that says how a slot is documented: the README in the slot's folder, one README per slot version, what the previous version's README is named, and the deprecation note at its top.

Why: nothing says any of this today. Every slot in a frontend-base app has a README.md next to its component, and a slot with two versions has a README.v1.md beside it (frontend-app-authoring's CourseAuthoringUnitSidebarSlot has both, and the site operators' slot reference on docs.openedx.org links straight to the README.v1.md). That is a convention everyone follows and nobody wrote down.

#344 adds a how-to for versioning and renaming slots. Its examples show the README names (README.v1.md for a previous version; README.songList.v1.md for a renamed slot, the old README being named for the old slot minus what its id shares with the current one), but a how-to is the wrong place to state the rule, so the rule is shown by example and explained nowhere.

docs/ in this repo has two kinds of document: how_tos/ and decisions/. Neither fits. ADR 0009 is the slot naming and lifecycle record and says nothing about documentation; a file-naming convention is not a behaviour decision, so it does not belong in that ADR or in a new one. The sibling repos have the same two kinds (frontend-plugin-framework, frontend-platform and frontend-app-authoring have decisions/ and how_tos/; frontend-app-learning and paragon have decisions/ only), so there is no precedent in the ecosystem's frontend repos for a third kind.

Claude Plan

Open questions, in the order they would need answering:

  1. Where it lives: a new docs/references/ (or similar) in this repo; a developer-facing page on docs.openedx.org; or a section of an existing how-to such as the migration how-to's "Refactor slots".
  2. What it covers: the slot folder and its README.md; one README per slot version and per renamed slot, with the naming rule for the previous one; the deprecation note at the top of a previous README; the link from the current README to the previous one; whether an app's own slot index (such as src/plugin-slots/README.md) is part of the convention.
  3. Whether the site operators' slot reference on docs.openedx.org should point to it, so the README it links to is explained somewhere.

What this issue does not propose: changing ADR 0009, or what the #344 how-to shows.

主要言語
TypeScript
スター
4
フォーク
13
平均マージ
3日 5時間
マージ済み PR(30日)
4

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

openedx/frontend-base のほかの issue

openedx/frontend-base の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。