mdmark

版を上げる

mdmark upgrade で移行の手順を当てて、設定・索引・文書を新しい版に合わせる手順

mdmark の新しい版を使い始めるときに実行する。 呼んだ CLI の版が目標の版になり、設定の version（手元の版）より新しく目標の版以下の版の移行の手順を、版の順に当てる。

前提

手順

当てる範囲を確かめる

--plan で呼ぶ

npx github:shuhei1101/mdmark#v{目標の版} upgrade --plan

{目標の版} は上げる先の版の {MAJOR}.{MINOR}.{PATCH}。 手元の版は設定の version。 version が無い設定（v0.3.0 までの init が置いた設定）では、標準エラーに問いが出るので、標準入力に手元の版を v{MAJOR}.{MINOR}.{PATCH} の形で答える。 何も書き換えず、当てる版ごとの手順・変更履歴の行・壊す手順の有無を出す。

手元の版: v0.3.0
目標の版: v0.5.0
v0.4.0:
  rename_key: `build.out` を `build.output` に改める
v0.5.0:
  replace_mark（壊す手順）: 印 `<!-- note -->` を `<!-- callout -->` に書き換える
変更履歴:
  v0.4.0 #40 版を上げるときに移行の手順を当てる mdmark upgrade を作る
  v0.5.0 #45 注意書きの印の名前を揃える
--plan のため書き換えていません

手元の版が目標の版と同じときは 手元の版が目標の版と同じです。当てる手順はありません と出て、ここで終わる。

壊す手順を読む

（壊す手順） が付いた手順は、当てると値が失われる。 当ててよいかを、手順の説明と変更履歴の行から決める。

移行の手順を当てる

upgrade を呼ぶ

npx github:shuhei1101/mdmark#v{目標の版} upgrade

次の順に処理する。

  1. 手元の版を聞く（設定に version が無いときだけ）
  2. 値を聞く手順の問いに答える（手順がキーを足すために値を聞くときだけ）
  3. 壊す手順を当ててよいかの確かめに y で答える（壊す手順があるときだけ）
  4. 設定・索引・文書の写しを .mdmark/backup/{日時}/ に取り、手順を版の順に当てる
  5. mdmark check と同じ点検を流し、ずれが 0 件なら設定の version を目標の版に書き換える

問いは標準エラーに出て、答えは 1 問 1 行で標準入力から読む。 y 以外を答えると、何も書き換えずに終わる。 --yes を付けると、壊す手順の確かめだけを飛ばす。 手元の版と、値を聞く手順の問いは飛ばさない。

当てた手順・変更履歴の行・写しの場所が出る。

写し: .mdmark/backup/20261017120000
版を v0.5.0 にしました

使う側のページの配布物の URL のタグを書き換える

upgrade が書き換えるのは設定・索引・文書だけ。 使う側のページに書いた配布物の URL のタグは、手で v{目標の版} に書き換える（配布物を読み込む）。

失敗したとき

手順の失敗と点検のずれは、写しから全てのファイルを戻し、設定の version を変えずに終了コード 1 で終わる。 標準エラーに、失敗した版・手順・理由か、mdmark check と同じ形のずれの行が出る。 原因を直して、同じ upgrade をもう一度呼ぶ。 次の upgrade は、同じ手元の版から当て直す。

そのほかの終了コード 1 は CLI。

反映

即時。upgrade が終わると、設定の version が目標の版になり、手順の変更が設定・索引・文書に入っている。 ページは、URL のタグを書き換えて再読み込みしたときから目標の版を読み込む。

確認

設定の版が目標の版になっている

mdmark.config.yaml の version が v{目標の版} になっている。

点検が通る

npx github:shuhei1101/mdmark#v{目標の版} check

ずれ 0 件 が出る（点検する）。

元に戻す

.mdmark/backup/{日時}/ の写しのファイルを、設定ファイルのあるフォルダの同じ相対パスへ戻し、ページの URL のタグも戻す。 .mdmark/ は中身が * の .gitignore を持つため、git の対象にならない。 写しが要らなくなったら消す。