ローカル環境と本番環境のrevisions.ymlを分ける & script定義追加

Author: na-trium-144

.github/workflows/node.js.yml

@@ -45,4 +45,4 @@ jobs:
         node-version: ${{ matrix.node-version }}
         cache: 'npm'
     - run: npm ci
-    - run: npm run checkDocs
+    - run: npx tsx ./scripts/checkDocs.ts

.gitignore

@@ -3,9 +3,11 @@
 /.open-next
 /cloudflare-env.d.ts
 
-# generated docs section file lists (regenerated by npm run generateDocsMeta)
+# documentation
 /public/docs/**/sections.*
 /public/docs/languages.*
+/public/docs/revisions-dev.yml
+/public/docs/commits-dev.yml
 
 # dependencies
 /node_modules

README.md

@@ -39,12 +39,12 @@ GITHUB_CLIENT_SECRET=
 
 別のターミナルで、
 ```bash
-npx drizzle-kit migrate
+npm run db-migrate
 ```
 でデータベースを初期化
 
 ```bash
-npx tsx ./scripts/checkDocs.ts --write
+npm run db-docs
 ```
 でデータベースにドキュメントのページ情報を挿入します。
 (public/docs/以下にmarkdownを追加・削除したら再度実行する必要があります)
@@ -66,7 +66,7 @@ npm run lint
 
 ### データベースのスキーマ
 
-* データベースのスキーマ(./app/schema/hoge.ts)を編集した場合、 `npx drizzle-kit generate` でmigrationファイルを作成し、 `npx drizzle-kit migrate` でデータベースに反映します。
+* データベースのスキーマ(./app/schema/hoge.ts)を編集した場合、 `npm run db-generate` (`npx drizzle-kit generate`) でmigrationファイルを作成し、 `npm run db-migrate` (`npx drizzle-kit migrate`) でデータベースに反映します。
     * 本番環境のデータベースのmigrateはmainにpushされた際にGitHub Actionで実行されます
 * スキーマのファイルを追加した場合は app/lib/drizzle.ts でimportを追加する必要があります(たぶん)
 * `npx prisma dev` で立ち上げたデータベースは `npx prisma dev ls` でデータベース名の確認・ `npx prisma dev rm default` で削除ができるらしい
@@ -128,8 +128,8 @@ npm run checkDocs
 * REPLのコード例は1セクションに最大1つまで。
     * コードエディターとコード実行ブロックはいくつでも置けます。
 * ページ0以外の各ページの最後はレベル2見出し「この章のまとめ」と、レベル3見出し「練習問題n」を置く
-* 編集したドキュメントにローカルの開発環境でアクセスする際は `npx tsx ./scripts/checkDocs.ts --write` でrevisions.ymlを更新してください。チャットを正しく動作させるために必要です。基本的には手動でこのファイルを編集する必要はありません。
-    * 本番環境ではドキュメントの変更がmainブランチにpushされた際に自動で更新されます。gitのコミットidを参照して更新するため、ローカルで更新したrevisions.ymlはpushしないでください。
+* 編集したドキュメントにローカルの開発環境でアクセスする際は `npm run db-docs` を実行してください。これにより `public/docs/revisions-dev.yml` が更新・作成され、チャットが正しく動作するようになります。
+    * 本番環境用の `revisions.yml` は、main ブランチに push された際に GitHub Action によって自動的に更新されます。
 
 ### ベースとなるドキュメントの作り方
 

app/lib/docs.ts

@@ -218,7 +218,9 @@ export async function getPagesList(): Promise<LanguageEntry[]> {
 export async function getRevisions(
   sectionId: SectionId
 ): Promise<RevisionYmlEntry | undefined> {
-  const revisionsYml = await readPublicFile(`docs/revisions.yml`);
+  const revisionsYml = await readPublicFile(
+    `docs/revisions${process.env.NODE_ENV === "development" ? "-dev" : ""}.yml`
+  );
   return (yaml.load(revisionsYml) as Record<string, RevisionYmlEntry>)[
     sectionId
   ];
@@ -230,7 +232,9 @@ export async function getCommitDate(id: string): Promise<Date> {
     return commitDateCache.get(id)!;
   }
   const p = (async () => {
-    const commitInfoYml = await readPublicFile(`docs/commits.yml`);
+    const commitInfoYml = await readPublicFile(
+      `docs/commits${process.env.NODE_ENV === "development" ? "-dev" : ""}.yml`
+    );
     const commitInfo = yaml.load(commitInfoYml) as Record<string, string>;
     const timestamp = commitInfo[id];
     if (timestamp) {

package.json

@@ -14,7 +14,9 @@
     "lint": "npm run cf-typegen && next lint",
     "tsc": "npm run cf-typegen && tsc",
     "format": "prettier --write app/ packages/",
-    "checkDocs": "tsx ./scripts/checkDocs.ts",
+    "db-migrate": "drizzle-kit migrate",
+    "db-generate": "drizzle-kit generate",
+    "db-docs": "tsx ./scripts/checkDocs.ts --write",
     "cf-preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview --port 3000",
     "cf-deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
     "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"

scripts/checkDocs.ts

@@ -4,14 +4,17 @@ mainブランチにpushされた際にGitHub Actionが --write 引数をつけ
 現在のパス、md5ハッシュ、コミットIDなどを ./public/docs/revisions.yml に追記
 セクションIDとページパスの対応関係をデータベースに反映
 
+ローカルで --write 引数をつけて実行した場合(npm run db-docs でもok)、
+./public/docs/revisions-dev.yml に書き込む。これは開発環境で使われ、pushされない。
+
 過去に存在したページが削除されている場合、エラーになります。
 その場合は手動でrevisions.ymlを編集し、古いページ名の記述を新しいページ名に置き換える必要がある
 (できれば自動化したいが、いい方法が思いつかない)
 
 Dockerfile内で --check-diff 引数をつけて実行され、
 revisions.ymlが最新の状態でないならexit(1)をし、dockerのビルドを停止します
 
-なにも引数をつけずに実行した場合(npm run checkDocs)、
+なにも引数をつけずに実行した場合、
 変更があってもなにもせず正常終了します
 エラーなく全ドキュメントを取得できるかどうかの確認に使います
 */
@@ -43,6 +46,11 @@ if (process.argv[2] === "--write") {
 
 const docsDir = join(process.cwd(), "public", "docs");
 
+const useDevFiles = doWrite && !process.env.GITHUB_ACTIONS;
+const revisionsFilename = useDevFiles ? "revisions-dev.yml" : "revisions.yml";
+const commitsFilename = useDevFiles ? "commits-dev.yml" : "commits.yml";
+console.log(`Using ${revisionsFilename} and ${commitsFilename}`);
+
 let commit = "";
 if (doWrite) {
   commit = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
@@ -54,9 +62,12 @@ let hasNewRevision = false;
 
 const langEntries = await getPagesList();
 
-const revisionsPrevYml = existsSync(join(docsDir, "revisions.yml"))
-  ? await readFile(join(docsDir, "revisions.yml"), "utf-8")
-  : "{}";
+let revisionsPrevYml = "{}";
+if (existsSync(join(docsDir, revisionsFilename))) {
+  revisionsPrevYml = await readFile(join(docsDir, revisionsFilename), "utf-8");
+} else if (existsSync(join(docsDir, "revisions.yml"))) {
+  revisionsPrevYml = await readFile(join(docsDir, "revisions.yml"), "utf-8");
+}
 const revisions = yaml.load(revisionsPrevYml) as Record<
   string,
   RevisionYmlEntry
@@ -142,28 +153,32 @@ if (doWrite) {
     noArrayIndent: true,
   });
   await writeFile(
-    join(docsDir, "revisions.yml"),
+    join(docsDir, revisionsFilename),
     "# This file will be updated by CI. Do not edit manually, unless CI failed.\n" +
       revisionsYml,
     "utf-8"
   );
 
+  let commitsPrevYml = "{}";
+  if (existsSync(join(docsDir, commitsFilename))) {
+    commitsPrevYml = await readFile(join(docsDir, commitsFilename), "utf-8");
+  } else if (existsSync(join(docsDir, "commits.yml"))) {
+    commitsPrevYml = await readFile(join(docsDir, "commits.yml"), "utf-8");
+  }
+  const commitsYml = yaml.load(commitsPrevYml) as Record<string, string>;
   if (hasNewRevision) {
-    const commitsYml = yaml.load(
-      await readFile(join(docsDir, "commits.yml"), "utf-8")
-    ) as Record<string, string>;
     commitsYml[commit] = execFileSync(
       "git",
       ["show", "-s", "--format=%cI", commit],
       {
         encoding: "utf8",
       }
     ).trim();
-    await writeFile(
-      join(docsDir, "commits.yml"),
-      "# This file will be updated by CI. Do not edit manually.\n" +
-        yaml.dump(commitsYml, { sortKeys: true }),
-      "utf-8"
-    );
   }
+  await writeFile(
+    join(docsDir, commitsFilename),
+    "# This file will be updated by CI. Do not edit manually.\n" +
+      yaml.dump(commitsYml, { sortKeys: true }),
+    "utf-8"
+  );
 }