mdmark

版を上げる仕組み

版ごとの移行の手順を版の順に当て、写しから戻し、点検してから版を書き換える流れ

mdmark upgrade が、設定・索引・文書を新しい版に合わせる考え方。 手順は 版を上げる。

当てるまでの流れ

1. 目標の版を、呼んだ CLI の版にする。引数では受けない。手元の版は設定の version から読み、無ければ聞く
2. 手元の版が目標の版と同じなら何も当てず、手元の版が新しければ手元の版以上の CLI で呼び直すことを示して止まる
3. 手元の版より新しく目標の版以下の版の steps.yaml を、版の順に読み、形が合うかを確かめる。1 つでも合わなければ何も書き換えない
4. 値を聞く手順の問いと、壊す手順の確かめを、書き換えの前に聞く
5. 書き換えうるファイルの写しを取り、手順を版の順に当てる
6. mdmark check と同じ点検を流し、ずれが 0 件のときだけ設定の version を目標の版に書き換える

手順を持たない版は飛ばす。 --plan は 3 で止まり、何も書き換えない。

移行の手順

版ごとの migrations/{版}/steps.yaml に、mdmark の開発者が手順を並べる。 手順の種類は次の 5 つ。

種類	当てること
rename_key	設定・索引のキーの名前を変える
set_default	設定・索引に無いキーを足す。値は手順に書くか、利用者に聞く
map_values	設定・索引のキーの値を、表のとおりに読み替える
replace_mark	文書の印を書き換える
call	宣言で書けない移行を、同梱のスクリプトで当てる

どの手順も、既に当たった後の状態に当てても結果が変わらない。 値が失われる手順には壊す印が付き、--yes が無いとき当てる前に確かめる。 設定・索引はコメント・キーの並び・触らないキーの書き方を残して書き換える。

失敗したとき

手順の失敗か点検のずれがあると、写しの全てのファイルを元の場所へ戻し、設定の version を変えない。 写しは、設定ファイルのあるフォルダの .mdmark/backup/{日時}/ に残る。 戻す前に止まっても（Ctrl-C など）、設定の version は手元の版のままなので、次の upgrade が同じ手元の版から当て直す。 手順が当て直しても結果の変わらない形のため、当たった手順をもう一度当てても壊れない。

変更履歴

当てた範囲（手元の版より新しく目標の版以下）の変更履歴の行を、手順と一緒に出す。 行は 変更履歴 の表から取る。