メインコンテンツまでスキップ

環境構築からプルリクエストまでの流れ

環境構築から執筆、公開までの流れと手順を説明します。

issueの確認​

本プロジェクトではチケット駆動を原則としています。加えようとしている変更についてのissueがあるか、十分に議論が交されているかなどを確認してください。

編集環境のセットアップ​

リポジトリをGitHub上でフォークし、フォークしたリポジトリをチェックアウトします。(当リポジトリにコミット権限がある方はフォークする必要はありません。)

shell
# 一般の方
git clone git@github.com:自分のアカウント/フォーク先のリポジトリ名.git
# 当プロジェクトにコミット権限がある方
git clone git@github.com:yytypescript/book.git
shell
# 一般の方
git clone git@github.com:自分のアカウント/フォーク先のリポジトリ名.git
# 当プロジェクトにコミット権限がある方
git clone git@github.com:yytypescript/book.git

Devboxを使って再現性のある環境を構築します。DevboxではNode.jsやBunなど執筆に必要なツールの導入のために利用しています。まだインストールしていない方はDevboxの公式サイトのインストール手順を参照してください。

Devboxで開発用シェルを起動します。

shell
devbox shell
shell
devbox shell
Direnvをご利用ください(任意だが推奨)

毎回devbox shellを実行するのが面倒な場合は、Direnvをお使いください。Direnvを導入している方は次のコマンドを実行して、.envrcの実行を許可してください。

shell
direnv allow
shell
direnv allow

必要なパッケージをインストールします。

shell
bun install
shell
bun install

開発サーバーを起動します。

shell
task start
shell
task start

開発サーバーの起動には結構な時間がかかります。プロセスを停止せずにお待ちください。

開発サーバーが起動したら、ブラウザでhttp://localhost:3000を開きます。

ブランチを作る​

ブランチを作成します。

bash
git checkout -b ブランチ名
bash
git checkout -b ブランチ名

masterブランチには直接pushできません。そのため変更はブランチで行う必要があります。

コンテンツを作る​

新規ページを追加する場合​

docsディレクトリに新規ページのMarkdownファイルを追加します。

shell
mkdir -p docs/カテゴリ名/サブカテゴリ名
touch docs/カテゴリ名/サブカテゴリ名/new-page.md
shell
mkdir -p docs/カテゴリ名/サブカテゴリ名
touch docs/カテゴリ名/サブカテゴリ名/new-page.md

sidebars.jsに新規ページへのパスを追加します。パスには拡張子.mdを含めません。

sidebars.js
js
module.exports = {
  // ...
  tutorialSidebar: [
    {
      type: "category",
      label: "カテゴリ名",
      items: [
        {
          type: "category",
          label: "サブカテゴリ名",
          items: [
            // highlight-next-line
            "カテゴリ名/サブカテゴリ名/new-page",
          ],
        },
      ],
    },
  ],
};
sidebars.js
js
module.exports = {
  // ...
  tutorialSidebar: [
    {
      type: "category",
      label: "カテゴリ名",
      items: [
        {
          type: "category",
          label: "サブカテゴリ名",
          items: [
            // highlight-next-line
            "カテゴリ名/サブカテゴリ名/new-page",
          ],
        },
      ],
    },
  ],
};

ここまで完了したら、作成したファイルを編集していきます。

既存ページを変更する場合​

既存ページを変更する場合は、docsディレクトリから当該ファイルを探して編集してください。

既存ページを移動する場合​

  1. ファイルを移動、またはファイル名を変更します。
  2. sidebars.jsの該当ページのパスを新しいパスに更新します。
  3. vercel.jsonのredirectsに旧URLから新URLへのリダイレクト設定を追加します。
  4. task buildを実行し、リンク切れがないか確認します。

たとえば、docs/tutorials/setup.md を docs/getting-started/setup.md に移動した場合は、sidebars.js の
"tutorials/setup" を "getting-started/setup" に修正し、vercel.json の redirects には次の設定を追加します。

vercel.json
json
{ "source": "/tutorials/setup", "destination": "/getting-started/setup" }
vercel.json
json
{ "source": "/tutorials/setup", "destination": "/getting-started/setup" }

これらの変更後、task build を実行してリンク切れがないか確認します。

コンテンツ編集時に知っておくとよいこと​

📄️ VS Codeで編集する

Markdownファイルを編集するエディターはVS Codeがお勧めです。

📄️ Markdown

Markdownは標準的な記法に加えて、本プロジェクトで独自拡張した仕様があります。

📄️ ファイル構成

どこにどのようなファイルがあるかを説明します。

変更をチェックする​

変更をチェックするには、task checkを実行してください。

shell
task check
shell
task check

このコマンドは、コードスタイル、Markdown、日本語、型チェックを行います。もしチェックに失敗した場合は、後述の「トラブルシューティング」を参照してください。

チュートリアルに変更を加えた場合は、可能であれば回帰テストを行ってください。

コミットする​

作成したファイルを編集したらコミットします。

shell
git add docs/カテゴリ名/サブカテゴリ名/new-page.md
git commit -m "「新しいページ」を追加しました。"
shell
git add docs/カテゴリ名/サブカテゴリ名/new-page.md
git commit -m "「新しいページ」を追加しました。"
ヒント

このプロジェクトは日本語話者向けなので、コミットメッセージは日本語で構いません。

コミットメッセージの例:

  • 「型注釈」を追加しました。
  • 「関数」にサンプルコードを追加しました。
  • 誤字「使用」を「仕様」に修正しました。

プルリクエストを送る​

注意

プルリクエストを送る前にできるだけコミットが1つになっているか確認してください。

変更内容をpushします。

shell
git push -u origin ブランチ名
shell
git push -u origin ブランチ名

プルリクエストの作成時にはGitHubのキーワードを用いたissueの関連付け機能を用いて、対応したissueをプルリクエストに関連付けてください。これには2つの目的があります。ひとつは、プルリクエストの経緯をたどれるようにすることです。もうひとつは、プルリクエストがマージされた際に、issueが自動クローズされるようにするためです。たとえば、issue #123を解決するプルリクエストであれば、本文中に次のようなキーワードを書きます。

markdown
Close #123
markdown
Close #123

これはチケット駆動プロセスで必要となる手順です。

📄️ チケット駆動(プルリクする前に話し合おう)

「着手する前に話し合おう」をチケット駆動で行う流れについて説明します。

プルリクエストが作成されると、CIが走りコードスタイルなどのチェックが行われます。CIに問題がなければメンテナーによってマージされます。マージ権限がある方は、CIの結果を確認の上、問題なければ自分でマージして構いません。

トラブルシューティング​

task check:format(Prettier)が失敗する​

task formatを実行して自動修正を行ってください。

注意

task formatはファイルを変更します。万が一に備えて、git addやgit commitなどをして、簡単に元に戻せるようにしてから実行してください。

Prettierの自動整形をさせたくないコードブロックには<!--prettier-ignore-->をつけます。

markdown
<!--prettier-ignore-->
```ts
type Code =
  | 1
  | 2
  | 3;
```
markdown
<!--prettier-ignore-->
```ts
type Code =
  | 1
  | 2
  | 3;
```

task check:markdown(markdownlint)が失敗する​

markdownlintで指摘されたエラーの詳細はmarkdownlintのドキュメントをご覧ください。

markdownlintのエラーの中には、task check:markdown:fixを実行することで自動修正できるものがあります。そうでないエラーは手動で修正してください。

注意

task check:markdown:fixはファイルを変更します。万が一に備えて、git addやgit commitなどをして、簡単に元に戻せるようにしてから実行してください。

task check:japanese(textlint)が失敗する​

textlintのエラーが出ない書き方が望ましいです。textlintのエラーの中には、task check:japanese:fixを実行することで自動修正できるものがあります。そうでないエラーは手動で修正してください。

注意

task check:japanese:fixはファイルを変更します。万が一に備えて、git addやgit commitなどをして、簡単に元に戻せるようにしてから実行してください。

場合によって、textlintを無効にしたいことがあるかもしれません。無効化したい部分はコメントで囲みます。

markdown
...
<!--textlint-disable prh-->
textlintのprhルールが無効になるエリア
<!--textlint-enable prh-->
...
markdown
...
<!--textlint-disable prh-->
textlintのprhルールが無効になるエリア
<!--textlint-enable prh-->
...

注意点として、コメントの前後には空行が必要です。

NG
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->
NG
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->
OK
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->
OK
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->
  • 質問する ─ 読んでも分からなかったこと、TypeScriptで分からないこと、お気軽にGitHubまで🙂
  • 問題を報告する ─ 文章やサンプルコードなどの誤植はお知らせください。