構成と運用
本ガイドラインの構成
Github、Starlightを使用してガイドラインを構築しています。
ウェブサイト制作に必要なカテゴリーとして、
- 制作前
- 制作中
- 制作後
- コーディングのスタイル
- ファイル構成
- 命名規則
- CSSの書き方
- 各UI実装の考慮・注意点・具体例（準備中）
という順で構成されています。
各ページは以下のコンポーネントで構成されています。
- header
- テキスト検索
- GitHubリポジトリへのリンク
- テーマ切り替え
- 言語設定
- sidebar
- カテゴリー
- 公開されている全てのページへのリンク
- contents
- そのページのことが記載されています
- TOC（目次）
- ページのアウトラインに沿って目次が生成されます。h3までを対象としています
- footer
- そのページの最終更新日
- 前・次のページへのナビゲーション
開発環境（準備中）
本ガイドラインに適合するための静的テストなどを組み込んだ開発環境と、独自に対応する場合の手がかりを提供します。
そのため、「なぜ（Why）」ではなく「どうやって（How）」については、このガイドラインの読み込みに重点を置かなくても静的テスト（リント）を使用するだけでおおよそ達成できるでしょう。
静的テストは少しずつ更新されます。なぜこのルールを守る必要があるのか疑問に思った場合は、本ガイドラインを読み返してみてください。
本ガイドラインの運用
本ガイドラインのメインコントリビューターはガイドラインの更新があった場合に適切なチャネルで更新を全体にアナウンスします。 またCHANGELOGを残し、アップデートが後からわかるように管理します。
バージョニング
このガイドラインはコーディングファクトリーのガイドラインをリニューアルする目的で作成されました。すべてのページを新規で作成しましたが、過去のガイドラインを発展させるという目的が始まりとなっていますので、バージョンは8.0からスタートします。 バージョンをどの様に上げるかについては以下のように考えます。
バージョニングしないもの
- 文章の内容理解に関係しないタイポなどの修正
マイナーバージョンアップとなるもの
マイナーバージョンの数値の上がり方（0.1なのか0.0.1なのか）についてはワーキンググループで協議しケースバイケースで決定します。
複数の改修についてもマイナーバージョンアップで対応可能ですが、アップデートの量が多い場合はメジャーバージョンアップデートとする可能性もあります。
- 見出しを伴うような単独の新規コンテンツの追加
- サンプルコードの追加
- 既存コンテンツへ補足情報の追加
- 既存コンテンツの内容理解に関わる修正
メジャーバージョンアップとなるもの
- 新規ページの追加
- ただし、既存コンテンツをより詳細に説明するためのサブページ等の場合はマイナーバージョンアップとなる可能性もあります。
- あらため予定されていた大きな改修（ガイドラインの装飾としてのテーマ変更やガイドラインサイト自体への機能追加）
- 既存のコンテンツとは方向性が変わる内容のアップデート
ガイドライン内容の更新について
ガイドラインワーキンググループまたはその他の方、どちらも以下の手順で更新します。
-
issueの登録
- テンプレートを複数用意していますので適切なものを選択してください
- issueがGitHub上で誰かにアサインされると最新のmainブランチからissueブランチが作成され、ドラフト状態でPRも作成されます
-
プルリクエストによるレビューと検討
- リポジトリのコントリビューター内でのヒエラルキーはありません。レビューに参加をお願いします
- ドラフトであっても差分がリモートにpushされていればブランチ名をサブドメインにもったプレビューをブラウザで確認できます。チャットなどで積極的に周知しましょう
-
承認（2名以上）
- 2名以上の承認でマージ可能です。2人目の承認者がなかなか現れない場合はチャットなどで広く依頼をかけてください
- 誤字脱字の修正の承認については1名で構いません
- バージョニングするかどうか検討します。
-
ガイドラインに追加（または改修）される
本ガイドラインは校了を経て、リポジトリとともに一般に公開することを計画しています。
公開された場合はGitHubアカウントを持っていればどなたでもissueを立てることが可能です。
外部からのissueに対してどのようにガイドラインに取り込むかは弊社内で検討します。
ガイドライン環境の更新について
メインコントリビューターは四半期を目安に依存ライブラリのアップデート確認や修正を行います。 修正手順はガイドライン内容の更新と同一です。